From f2ff46cdf2b0fc9dc437ec541afc27194553d6e7 Mon Sep 17 00:00:00 2001 From: Christian Vogel Date: Mon, 22 Feb 2016 11:48:33 +0000 Subject: [PATCH 001/241] initial RAML 1.0 RC1 version to open source --- .gitignore | 3 + README.md | 64 +- raml-0.8.md => versions/raml-08/raml-08.md | 6 +- versions/raml-10/images/typesHierarchy.png | Bin 0 -> 27968 bytes versions/raml-10/raml-10.md | 3321 ++++++++++++++++++++ 5 files changed, 3343 insertions(+), 51 deletions(-) create mode 100644 .gitignore rename raml-0.8.md => versions/raml-08/raml-08.md (99%) create mode 100644 versions/raml-10/images/typesHierarchy.png create mode 100644 versions/raml-10/raml-10.md diff --git a/.gitignore b/.gitignore new file mode 100644 index 00000000..46e2489c --- /dev/null +++ b/.gitignore @@ -0,0 +1,3 @@ +# MAC OS + +.DS_Store diff --git a/README.md b/README.md index 64310bbd..97fb56e5 100644 --- a/README.md +++ b/README.md @@ -1,62 +1,32 @@ # The RESTful API Modeling Language (RAML) Spec -###Licensing +RAML is a language for the definition of HTTP-based APIs that embody most or all of the principles of Representational State Transfer (REST). The RAML specification (this document) defines an application of the [YAML 1.2 specification](http://yaml.org/spec/1.2/spec.html) that provides mechanisms for the definition of practically-RESTful APIs, while providing provisions with which source code generators for client and server source code and comprehensive user documentation can be created. -[Branding Guidelines](http://raml.org/licensing.html) - -## Index - -###[Introduction:](https://github.com/raml-org/raml-spec/blob/master/raml-0.8.md#introduction) -[RAML Overview](https://github.com/raml-org/raml-spec/blob/master/raml-0.8.md#overview) -[RAML Markup Language](https://github.com/raml-org/raml-spec/blob/master/raml-0.8.md#markup-language) - -####[Includes](https://github.com/raml-org/raml-spec/blob/master/raml-0.8.md#includes) +The current version of the RAML specification is **1.0** and can be found [here](versions/raml-10/raml-10.md). -Named Parameters: +## IMPORTANT NOTE -[Named Parameters with Multiple Types](https://github.com/raml-org/raml-spec/blob/master/raml-0.8.md#named-parameters-with-multiple-types) +RAML 1.0 is currently in a Release Candidate stage to gather feedback from the community around the features introduced in this version such as annotations or types. We will release the final version for 1.0 soon by announcing it on our [blog](http://blog.raml.org/). -Basic Information: +In the meanwhile, if you have any feedback, please report them [here](https://github.com/raml-org/raml-spec/issues). -[Root](https://github.com/raml-org/raml-spec/blob/master/raml-0.8.md#root-section) -[Base URI and baseUriParameters](https://github.com/raml-org/raml-spec/blob/master/raml-0.8.md#base-uri-and-baseuriparameters) -[Protocols](https://github.com/raml-org/raml-spec/blob/master/raml-0.8.md#protocols) -[Default Media Type](https://github.com/raml-org/raml-spec/blob/master/raml-0.8.md#default-media-type) -[Schemas](https://github.com/raml-org/raml-spec/blob/master/raml-0.8.md#schemas) -[URI Parameters](https://github.com/raml-org/raml-spec/blob/master/raml-0.8.md#uri-parameters) -[User Documentation](https://github.com/raml-org/raml-spec/blob/master/raml-0.8.md#user-documentation) +Current released version: 1.0 RC1 -Resources and Methods: +## Contributing -[Resources and Nested Resources](https://github.com/raml-org/raml-spec/blob/master/raml-0.8.md#resources-and-nested-resources) -[Template URIs and URI Parameters](https://github.com/raml-org/raml-spec/blob/master/raml-0.8.md#template-uris-and-uri-parameters) -[Absolute URI](https://github.com/raml-org/raml-spec/blob/master/raml-0.8.md#absolute-uri) -[Query Parameters](https://github.com/raml-org/raml-spec/blob/master/raml-0.8.md#query-strings) -[Body](https://github.com/raml-org/raml-spec/blob/master/raml-0.8.md#body) -[Web Forms](https://github.com/raml-org/raml-spec/blob/master/raml-0.8.md#web-forms) +We welcome any contributions from the community! You can contribute or provide feedback for the RAML Specification in different ways depending on your intentions. The following table illustrates the different ways to help us not only to improve the documentation of the specification, but also RAML itself. -Schemas and Responses: +|Your Intention |What to do?| +|:----------|:----------| +|You see a spelling or grammar mistake, or an error in our examples? | Fork this repository, make edits, and then submit a pull request. We will respond to your request as quickly as possible. +|You want to suggest a new feature, improve existing features, ask questions, or things general around the RAML specification? | File an issue. Please be as specific as possible about your intentions or what you’d like to see. -[Schemas](https://github.com/raml-org/raml-spec/blob/master/raml-0.8.md#schema) -[Responses](https://github.com/raml-org/raml-spec/blob/master/raml-0.8.md#responses) -[Headers](https://github.com/raml-org/raml-spec/blob/master/raml-0.8.md#headers) +You can also directly get in touch with us. Simply send us an email to: info@raml.org -Security: +**Note** -[Declaration](https://github.com/raml-org/raml-spec/blob/master/raml-0.8.md#declaration) -[Type](https://github.com/raml-org/raml-spec/blob/master/raml-0.8.md#type) -[OAuth 1.0](https://github.com/raml-org/raml-spec/blob/master/raml-0.8.md#oauth-10) -[OAuth 2.0](https://github.com/raml-org/raml-spec/blob/master/raml-0.8.md#oauth-20) -[Usage: Applying a Security Scheme to an API](https://github.com/raml-org/raml-spec/blob/master/raml-0.8.md#usage-applying-a-security-scheme-to-an-api) +Currently we are working on RC2 inside another branch called `raml-10-rc2`. If you want to fix any spelling or grammar mistake, or an error in our examples, please fork that branch, make your edits, and then submit a pull request. -###[References:](https://github.com/raml-org/raml-spec/blob/master/raml-0.8.md#references) -[Normative References](https://github.com/raml-org/raml-spec/blob/master/raml-0.8.md#normative-references) -[Informative References](https://github.com/raml-org/raml-spec/blob/master/raml-0.8.md#informative-references) +## Licensing -##Contributing - -Please [submit issues in this repository](https://github.com/raml-org/raml-spec/issues) to contribute to the evolution of the RAML specification. - -## Logos - -Download the RAML Logos in [JPG](https://github.com/raml-org/raml-spec/raw/master/logos/RAML-logo.jpg) and [EPS](https://github.com/raml-org/raml-spec/raw/master/logos/RAML-logo.eps) format. (For usage questions email [info@raml.org](mailto:info@raml.org)). +[Branding Guidelines](http://raml.org/licensing.html) diff --git a/raml-0.8.md b/versions/raml-08/raml-08.md similarity index 99% rename from raml-0.8.md rename to versions/raml-08/raml-08.md index b8163ee5..a3fec536 100644 --- a/raml-0.8.md +++ b/versions/raml-08/raml-08.md @@ -1,7 +1,5 @@ RAML™ Version 0.8: RESTful API Modeling Language -=================================== - -A [newer version of RAML (1.0)](http://raml.org/spec.html) is available. +================================== Abstract -------- @@ -975,7 +973,7 @@ This example shows an inline schema declaration. } ``` -Alternatively, the value of the *schema* field MAY be the name of a schema specified in the root-level *schemas* property (see [Named Parameters](#named-parameters), or it MAY be declared in an external file and included by using the by using the RAML !include user-defined data type. +Alternatively, the value of the *schema* field MAY be the name of a schema specified in the root-level *schemas* property (see [Named Parameters](#named-parameters), or it MAY be declared in an external file and included by using the RAML !include user-defined data type. This example repeats the /jobs resource definition, but with the schemas defined in the external files job.xsd and job.schema.json. diff --git a/versions/raml-10/images/typesHierarchy.png b/versions/raml-10/images/typesHierarchy.png new file mode 100644 index 0000000000000000000000000000000000000000..fe95f5f0855d03ff736fbd68e63d8403d178b41a GIT binary patch literal 27968 zcmeFZS6ov~)Hk~6qEggHk#0w&N|g@sV51635eOZmBas@KR23;omu>-(5_*SFRHR0F z4WTAN2mt~KAwbRs-}YU6zjH3n#p{LcBr~(utXcKH*7#aq_a57Ep5p)jusyi{uK@rs zfsYKW$C$x?oTrEV0l3NVN@o_hf_Mo->yOijd^Une6(a7_*&J3*;Ja%qR-RqXO+g1P0vegF1=2=q4KWzTg zP%S&{-i%Wwm=Sjv;xkYE*F*;lP&{W8wSSz-7z(}#&~^}`Z?!xa_bA=lo6ZTbMj?ao z1D%iq(_lFoZMc#vB_2V;rXa`|IWfdsikx`JdUm`BZ31m>PHsfdmXYEJ;`r-iY!JFl zP830H7W}i%ORsjgaQ=unW2oT4pHAc8lnZcbB_SA(OF=BJcvuj5(&g5Z(d*xqYH8yG z$yVa=K}ekYQ&wgiVShy^*pX6Xx$$NRPML(8sl1q)N=48_JsETHGk{s^l?oRYJ4seqM4X5xqwp3fUkFw^@??Sr6C) z_k~j}_dksN2g6yRQY=;h#3d~2{)#PkMMkH}c0ouzMkaXfrCu?0-#BPNPFy^Q>RY@= z>#_{6S|zTyWC!ovpu2FmK|>FB`d0K#v#Ke@A44jNxBuf2MfI`#gdZ{1var7mr5lyl z;8zWHUGkkY$Vol>>aS2}H`YI8x~;q;=?d}}hoIiWg*EK*1R-Ek9D@Gxe8sdJ$V=8! z)Q9H;PW_b_Jmw})45fULo8>t8!!I1;qvU@OgM%z^$))7ypW% z0rV_zZJhe1N6ajE3^r3+VbWQmx)nDw_J#&vw_5EOW0QV%$VPjT+_;urqbzyAez}s&E}yj`TIYaJ4w{JZX&4F zMJq_PisE)GRinEAas(K1U!!mB?K6%dl4D`91jU{FWZGzgcr!DaMnu$M>X+wIb5gCX z(#DG5iX|H1e>w7^PaD|js?;kz*@ri4s};@J9YUD1w$1F%aJ*&vwV7$T|D900M-5V? z&Ml#7TUeN-urgf;ctTB0^qvQ*@#zdlI%axHif;Dv)t3|Vrh9Hq@R0pdYbEwFnN)&35g_D5)0Abdr*d=;*}Kfmz3*c?8~_tmpHWRI z*#^vc4%TGCH|Ng<%ORDet_v|Q1!M>uj_~QU5BDl7CN08RTuZpn%l$6=0xAdM_Bbfc zLWExZaLD+n<>l1577mW?$O_q4RCot1xUiUGxuI<)RvEr;HKD{9=%nA`sK0i;B^ulP z^W|)Hi{#O~@nm}$Ppz*hKq=c)Hh&U~c?na&!+wCUCknuFxQV{k(mB@ATYEDG6Sp}7 zt@Q;&i%vX0#z+Uw%`J{{URL)lE$$y1V|La%*^RRIUTZN5Yj2qeL3vS`Lwr9`fJ(n# zEJA?<8P34Gzq70~F-S$zQF6N$9MQ?L^e5N6xyyx5Fo_0#E7(nqtWfZsy}OHH*z+Qy zsol;VZ4a(4YK^D<_NY`_=NUPqIMjbYY<_@WAp_zUf3o|XdcDmFc)HbEYi_3Ke)Ep5 z_KpIFPcY$LxASe&@YaZ=DT{U6N;Qe8OU*1pF`f@(4k@=vajklF&uBB~nZElCGo1BU za_jo*3KbJ7qR096?PY4Q@~Nq_;UMW0$rUy~vv8aJ8~Dc*DSu<3SD_y zG-nxBDJc9YQeD?=qq>y4g0{!&y-?E-wmmnDbovwuCBEdJjA?4?xz`fO(;zz$pVxS*T#6M zVIR8LU$Eu}-d;Kc{bLS6UQztj6pkb7=Yb_h9T|HRDN%}>@p zYjwLw3Zt$CSTZF@=kzg$Uo~onM!>4gPN1<@Dz%>45aVYzG9@zq9It}tJY)aQ0ZPSw z%A@eD(PiDPZ*9ifZPafaHB!d5=bkN>c8hQxI_@-EQ}au0Gav&7EAcBg{NeXLkbPe~ ztaWU!QS7;Hr{&SbTd=C^@Rih7;eR0wlFdCC6p1?W_&(Z0mjuk-%>-8)&%fp#?`Jh~ z`TBtzXBcV<)# zM>$xyj?P~Dr4!`4t+2cM46TrRUrds5r+&`yKB3{{sTS9$nGpIG4SS;6dUgd5AHMxs%T2gzavd0D$sTW5j;%M_LU0m?4TNoyWovV6bw4pV8PHv)I6e3Bq2gQy%G*i z>D@@JKPb%@LI!Jc_t~cD|7i^iB2#8uerL$jbBO(R)LV!7=?jP?GKGO80#f!6P>SC~ zgy32<~nw0^`HgQ(+GtGBR~!CVZksOO^|yNhGTGhtJnyQtJvc zv-hd^+LRw=-))N`LKH90Z7%1tXWyX5YL%N_NVEQaofb& zuIU+9#DZ*R-2DsQ32w@^pDyDh$b=fW*!;$Qq^4ig{rr2AZ8jhg3E9tNo+-QW z5@L9}oqs=$u0-Qu<6Mc1VR{_#_x`d%4YQ*7)CjuRQ|LTHEE#*%DS>qgf8`l z@>4w-s#+9_rAy^%5znz}3Cd&8%+rU4LM`4Uifc$OX*jHQ7GetlqMXwqj9@cviv3Fy5BRVl_A9qqJ8q&TK?e{MUu*!mSLQdZq7D!{I zD|w;N>@K(_MJW|a8S$4)U$aHGRe;3qP`!@SK;oXr{4GUv;<`u8XWv!ZzJnJHe{Lyi zQO&|y7=ytRsdt*sKXfpLotFeEug*WRT<&D>ye@F^G3E{ zxzB>H{3^NlC}4KRF(*?Iq;{eJ$=+=d?qz$c^CmbismAA$)Li# z_>Dp6%PwfASqODs-)lr+(p*?!{c>pE zsADHW&MlnJ=9S}+MI(+jkgTcXb!)u#)ja{lTY>DAct0ZQIPIK9z{U(ZkYM`Qrpv+f zIw(($QJwyBz92mq?SSCvA*i|u*T#KuwHUwNc*bDw`+rz7Z0GErOepv|(&vC8(LO1{ z*<^BLcBEVeHI+)s3Ndl(@xRQU$IDXpL33W+SFvuuQsE3UVhSlevLp_1no7TpBfP~r zsjlqZ&KCmn-nNHyv^j|;_c63Fc6Bl@J$>Du394WQr|&<)`k*^>{U$d5E{3>v zNq{Sw%cQo^)6&mahHEaKYfdmx&~i=W(+`_$(IVl<4kNd7#~jW-k2-S{qePv?TpiY` z^DQs7{C?RwS5xWh>4Oo0JiULcCCpMO>N#ScZZNJr51czaqPDJ$^w&OgIU>a;r~1}W zCl~Ob+V`%9?J;M(juV;H??52IzyKMuf7$&o4qN7WNft>!CUzsIkft<5!l!^|M`-G?=WDrR87z=S%O5AQ{v) zDaWNkb$^#54Q>p4=X#36$BaLP@^SaOfRU265VROw(^~K5=Nf z(xdw>39Lqb(m^SLvS;sgQkyU=o;uK7jLEk<*T2EKdwM4*zYuX~^-KWJnMv6P5kk#} z9mWZS(zcHGxJL3eEU^x9|dW=s))yycGwWIjZ#_HTTJTh(24ol!G+C40+=92o_ z-pb#;j+E(q(rldW?fo>tP}z;;XcVY55?T=)EbeY`ZCor%pajTQ9jc20xAg@u`VHl`I>q6T zz8>$dBAeqL*I5u9-`4c-LfShf4)!U*Lk`sat7X5SskA0`Zo_KVzP}6mApmES;GZ-T z!WF%()J*SD{QzWaRic!6#cka%0y1U$(`kbPCw(x{Lx0#n$~(yyKV$%&UD120^5kyw z7v~4SP7ccwn!Wp;^!pJk_YK6jIp+aBH*j225Nb}A`ggOw!smbb6{{2>4?U9?_+Fi=oE6hpn+3e4`T^`s&doi{7?o%h0BsKb;@Vrhn z^KmsDApKrWRCTl8SDc2dr4=pt(r_Hlt`s4mk7l;B$@PD1^HvVxTW}#32d~cv{^KVx zaFF0e*+Mse?e*&-KMMhX-}j9`8XdQ}y)99l2Ug%WYL`tfn+6#TJ9=9_BI7yU?9&~7 zHE`c3=j^sA%6K@48gBF76E%a3$Y;IL2f5>5mM;DNY^>e3>7$&HAWc-Q>U9ze0L0p9 z{$G|GaU2fv7NmxQF91iy+R^3if*hc}Y48XsQ$1Yn_x;iTm$yo29U_P3l+{CArAigF z3WBkV=v`l$^$L0+I(W(Uh>gk2^>-_Fr$s~d>JgAa!9t-7W%93qg`Q}47`3z|M+&P_ zySI$kfpG<`989OI-kZQ)yRp);Z+%XyUx>2Du}=~_2G9X%`*$~~AqQNki1~^hhy1w) zF1F{fixWl2<-A+VFx?9qI>sTm(&p4g!v3Fb6&cayyTgtzJ0XmrXo>~gw9s*)mNAsX za)g?yUH0$pc2f1t_x8p@ z$ni$O1s=EUAPZ#GeM&hZ=S0U|aCRy(87Tz37#K?#idU`P+$Xa!5ST;#b+ch>NJQC^ ze9pCrg435U{u8PV-Vl%)4_PH8Z=tK(&pz1(#=Q>e?Bl!KXehTxsXoAveY}nZKyZif zRq{;GLO)jqQ|L15j*KPMTUePzd@1wGn)q7%ESJE}_st?p;$*VGsOA0}W08SrSH4XEM-rUd3z7gJ|D%ogS8!gJfavE42Ls5J>7f807-;OE%ZY!B&(H zguv}?>isU7BkkFgXu8AvAsV{GF++TpOil=LH1}IG2SJs0N;RKPQMx_+p1A!gNs{)N zigMv;^508UC1tpXaY|_m$IhEyAC0MhI+^!WC}jC%a!fS|>)%HTtCo!$YSp=Xn?^&y zgHSzOVNPjSG~VTN8;V5VMH7-JL|AI6SWcOo1H{%eE!*FEnC{ldY+t6i1s2!!+|NHOQV|1FS%=OZ-%U`Ie{;3b|2i)@fjn zGs!6*e}rhu=Z|6S1iyATg{C z!?Oz5FdljgWm}%&AB-Ip4Cw5JLbhYkdz%O2Y=8^zw`}7z-ypYFdZIOTUF$r!qU>x8GfiW4-2OZ7c}GmY)%4 z@!1X&iCvy-Er}iC2-#W?X9?c+_?(x~IPUa&^u({p+x<)yVyB@4A39eetqy|4+|QIQ zde8X%VS%*N;YleEFDqDU-Ra$}-K1`NumW7fkK)al259K5>cBdZ$qbv?HJS*se} zIo-kaXs*B&;)~(^;p9ofucWWKDE|&o56GFt5wMbhAKqw+AD$a-o(vaL)e6!D-YI17 zUqmD>xU5(~6g#JR;)ZP<;>sz$!J}-~h<g|pdxzIuR##fYo+XcQCfe?J2Z~{ z0TQ=J9L+7`1xABJw`->~WU0QqAIEmHJj>UN`@wQBPnX$Er*X`sGR3M}T;8ZCr{
    `w5i#B{H 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 literal 0 HcmV?d00001 diff --git a/versions/raml-10/raml-10.md b/versions/raml-10/raml-10.md new file mode 100644 index 00000000..9f362570 --- /dev/null +++ b/versions/raml-10/raml-10.md @@ -0,0 +1,3321 @@ +# RAML Version 1.0: RESTful API Modeling Language + +## Abstract + +RAML is a language for the definition of HTTP-based APIs that embody most or all of the principles of Representational State Transfer (REST). The RAML specification (this document) defines an application of the [YAML 1.2 specification](http://yaml.org/spec/1.2/spec.html) that provides mechanisms for the definition of practically-RESTful APIs while providing provisions with which source code generators for client and server source code and comprehensive user documentation can be created. + +## Status of this Document + +This document reflects the RAML 1.0 specification. The contents of this document were derived from the consensus of its authors and through the feedback of RAML 0.8 users. We strongly recommend that implementers and users of the RAML 0.8 specification update their software and API definitions to this version of the RAML specification. + + +## Terminology and Conformance Language + +Normative text is text that describes elements of the specification that are indispensable and/or contain the conformance language keywords as defined by the [IETF RFC 2119](https://www.ietf.org/rfc/rfc2119.txt) "Key words for use in RFCs to Indicate Requirement Levels". Informative text is text that is potentially helpful to the user, but not indispensable to the specification and can be changed, added, or deleted editorially without negative implications to the implementation of the specification. Informative text does not contain any conformance keywords. + +All text in this document is, by default, normative. + +The keywords "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this document are to be interpreted as described in the [IETF RFC 2119](https://www.ietf.org/rfc/rfc2119.txt) "Keywords for use in RFCs to Indicate Requirement Levels". + +## Definitions and Terminology + +For this specification, **API definition** will be used to denote the description of an API using this specification and **RAML Specification** refers to the current document. + +**REST** is used in the context of an API implemented using some or all of the principles of REST. The REST acronym stands for Representational State Transfer and was first introduced and defined in 2000 by Roy Fielding in his doctoral dissertation [REST]. + +A **resource** is the conceptual mapping to an entity or set of entities. + +Throughout this specification, **markdown** means [GitHub-Flavored Markdown](https://help.github.com/articles/github-flavored-markdown/). + +Optional properties are indicated with trailing question marks (e.g. **description?**). + +## Introduction + +This specification describes the RESTful API Modeling Language (RAML). RAML is a human- and machine-readable language for the definition of a RESTful application programming interface (API). RAML is designed to improve the specification of such interfaces by providing a format that can serve as a useful contract between the API provider and the API consumers, for example to facilitate providing user documentation and source code stubs for client and server implementations, thereby streamlining and enhancing the definition and development of interoperable applications that utilize RESTful APIs. + +RAML introduces the innovative concept of resource types and traits for characterizing and reusing patterns of resources and methods on those resources, thereby minimizing the amount of repetition required to specify a RESTful API's design and promoting consistency within and across APIs. + +This document is organized as follows: + +* **Basic Information**. Explains how to describe core aspects of the API, such as its name, title, location (or URI), and defaults. Describes how to include supporting documentation for the API. +* **Data Types**. Describes a means to model API data via a streamlined type system, which also encompasses JSON and XML Schema. +* **Resources**. Describes how to specify an API's resources and nested resources, as well as URI parameters in any URI templates. +* **Methods**. Describes how to specify the methods on the API’s resources, and their request headers, query parameters, and request bodies. +* **Responses**. Describes the specification of API responses, including status codes, media types, response headers and response bodies. +* **Resource Types and Traits**. Describes the optional mechanism for using RAML resource types and traits to characterize resources so as to avoid unnecessary repetition in an API's definition and promote consistency and reuse. +* **Security**. Describes the mechanisms available in RAML to specify an API’s security schemes. +* **Annotations**. Describes a mechanism for extending a RAML specification by defining strongly-typed annotations and applying them throughout the specification. +* **Includes, Libraries, Overlays, and Extensions**. Describes how an API’s definition may be composed of externalized definition documents, how collections of such definitions can be packaged as libraries, how layers of metadata may be separated from and overlaid on top of a RAML document, and how an API specification can be extended with additional functionality. + +## What's New and Different in RAML 1.0 + +* **Data types**: a unified, streamlined, and powerful way to model data wherever it appears in an API. + * Uniformly covers bodies, URI parameters, headers, and query parameters (and no more need for a separate formParameters construct) + * Can wrap XML Schema and JSON Schema and even refer to sub-schemas within them, but in many cases just obviates them + * Much easier than JSON Schema or XML Schema, and all in YAML +* **Examples**: multiple examples, expressible in YAML, and annotatable (so semantics can be injected) +* **Annotations**: a tried-and-tested, strongly-typed mechanism for extensibility +* **Libraries**: more capable modularization for broad reuse of API artifacts +* **Overlays** and **Extensions**: further extensibility via separated files +* **Improved Security Schemes**: + * More complete OAuth support + * Support pass-through (key-based) security schemes + * Extension points +* **Several smaller changes** for consistency and expressivity, for example: + * Array-valued properties can be expressed as scalars when the array has only one member + * Ambiguities have been clarified, e.g. the optionality of baseUri and the overloading rules + +## Markup Language + +This specification uses [YAML 1.2](http://www.yaml.org/spec/1.2/spec.html) as its underlying format. YAML is a human-readable data format that aligns well with the design goals of this specification. As in YAML, all nodes (keys, values, tags, etc) are case-sensitive. + +RAML API definitions are YAML 1.2-compliant documents that begin with a REQUIRED YAML-comment line that indicates the RAML version, as follows. + +```yaml +#%RAML 1.0 +title: My API +``` + +The first line of a RAML API definition document MUST begin with the text _#%RAML_ followed by a single space followed by the text _1.0_ and nothing else before the end of the line. (RAML fragment documents begin similarly with the RAML version comment and a fragment identifier, but are not in themselves RAML API definition documents. See the section about [Modularization](#modularization) for more information.) + +This specification defines the media type _application/raml+yaml_ for RAML API definition documents, for documents that contain sections of RAML markup to be included in such API definitions and that are not more specifically described by another media type such as _application/schema+json_, and for overlay and extension documents that yield RAML API definition documents upon processing. The recommended filename extension for such files is _.raml_. + +In order to facilitate the automated processing of RAML documents, RAML imposes some restrictions and requirements in addition to the core YAML 1.2 specification. The following list enumerates some of these requirements and restrictions: + +1. The first line of a RAML file consists of a YAML comment that specifies the RAML version. Therefore RAML processors cannot completely ignore all YAML comments. +2. The order of some properties at given levels within a RAML document has significance. Therefore processors are expected to preserve this ordering. +3. Property names, also known as Keys, at given levels are not repeatable. Although YAML allows such repetition duplicate-keys will overwriting previously specified values. + +## The Root of the Document + +The root section of the RAML document describes the basic information of an API, such as its title and version, as well as defining assets used elsewhere in the RAML document such as types and traits. + +RAML-documented API definition properties MAY appear in any order. Processors MUST preserve the order of properties of the same kind within the same node of the definition tree, for example resources that appear at the same level of the resource tree, methods for a given resource, parameters for a given method, properties at the same level in a given type, etc. Processors MUST also preserve the order of items within arrays. + +This example shows a small part of a RAML API definition for the GitHub v3 public API. + +```yaml +#%RAML 1.0 +title: GitHub API +version: v3 +baseUri: https://api.github.com +mediaType: application/json +securitySchemes: + - oauth_2_0: !include securitySchemes/oauth_2_0.raml +types: + Gist: !include types/gist.raml + Gists: !include types/gists.raml +resourceTypes: + collection: !include types/collection.raml +traits: +securedBy: [ oauth_2_0 ] +/search: + /code: + type: collection + get: +``` + +The following table enumerates the possible properties at the root of a RAML document: + +| Property | Description | +|:----------|:----------| +| description? | A longer, human-friendly description of the API +| (<annotationName>)? | Annotations to be applied to this API. Annotations are any property whose key begins with "(" and ends with ")" and whose name (the part between the beginning and ending parentheses) is a declared annotation name. See section [Annotations](#annotation) for more information. +| schemas? | Alias for the equivalent "types" property, for compatibility with RAML 0.8. Deprecated - API definitions should use the "types" property, as the "schemas" alias for that property name may be removed in a future RAML version. The "types" property allows for XML and JSON schemas. +| types? | Declarations of (data) types for use within this API. See section [RAML Data Types](#raml-data-types) for more information. +| traits? | Declarations of traits for use within this API. See section [Resource Types and Traits](#resource-types-and-traits) for more information. +| resourceTypes? | Declarations of resource types for use within this API. See section [Resource Types and Traits](#resource-types-and-traits) for more information. +| annotationTypes? | Declarations of annotation types for use by annotations. See section [Annotation Types](#declaring-annotation-types) for more information. +| securitySchemes? | Declarations of security schemes for use within this API. See section [Security Schemes](#security-schemes) for more information. See section [Security Schemes](#security-schemes) for more information. +| uses? | Importing external libraries that can be used within the API. See section [Libraries](#libraries) for more information. +| title | Short plain-text label for the API +| version? | The version of the API, e.g. "v1" +| baseUri? | A URI that's to be used as the base of all the resources' URIs. Often used as the base of the URL of each resource, containing the location of the API. Can be a template URI. See section [Base URI and Base URI Parameters](#base-uri-and-base-uri-parameters) for more information. +| baseUriParameters? | Named parameters used in the baseUri (template). See section [Base URI and Base URI Parameters](#base-uri-and-base-uri-parameters) for more information. +| protocols? | The protocols supported by the API. The protocols property MUST contain one or more of the supported protocols: "HTTP", "HTTPS". (case-insensitive). +| mediaType? | The default media type to use for request and response bodies (payloads), e.g. "application/json" +| securedBy? | The security schemes that apply to every resource and method in the API. See section [Applying Security Schemes](#applying-security-schemes) for more information. +| /<relativeUri>? | The resources of the API, identified as relative URIs that begin with a slash (/). Every property whose key begins with a slash (/), and is either at the root of the API definition or is the child property of a resource property, is a resource property, e.g.: /users, /{groupId}, etc. +| documentation? | Additional overall documentation for the API. See section [User Documentation](#user-documentation) for more information. + +### API Title +The **title** property is a short plain text label for the API. It MUST be specified, and its value is a string. Its value SHOULD be suitable for use as a title for the contained user documentation. + +### API Version + +The OPTIONAL **version** property specifies a version of the API (as a whole). Its value is a string. API owners SHOULD consider carefully their versioning approach and communicate the current version through the version property. + +### API Description + +The OPTIONAL **description** property describes the overall API in a human friendly, extended manner. The value of the description property is a markdown string. More structured documentation SHOULD be included throughout the structure of the API definition and in the documentation property. + +### User Documentation + +The OPTIONAL **documentation** property includes a variety of documents that serve as user guides and reference documentation for the API. Such documents can clarify how the API works or provide technical and business context. + +The value of the documentation property is an array of one or more documents. Each document is an object that MUST contain exactly two properties, **title** and **content**, with non-empty string values. The content property's value is a markdown string. + +The structure of documentation object is described by following table. + +| Property | Description | +|:----------|:----------| +| title | Title of documentation section +| content | Content of documentation section + +This example shows an API definition with two user documents. + +```yaml +#%RAML 1.0 +title: ZEncoder API +baseUri: https://app.zencoder.com/api +documentation: + - title: Home + content: | + Welcome to the _Zencoder API_ Documentation. The _Zencoder API_ + allows you to connect your application to our encoding service + and encode videos without going through the web interface. You + may also benefit from one of our + [integration libraries](https://app.zencoder.com/docs/faq/basics/libraries) + for different languages. + - title: Legal + content: !include docs/legal.markdown +``` + +### Base URI and Base URI Parameters + +The OPTIONAL **baseUri** property specifies a URI as an identifier for the API as a whole, and MAY be used the specify the URL at which the API is served (its service endpoint), and which forms the base of the URLs of each of its resources. The baseUri property's value is a string that MUST conform to the URI specification [RFC2396](https://www.ietf.org/rfc/rfc2396.txt) or a Level 1 Template URI as defined in [RFC 6570](https://tools.ietf.org/html/rfc6570). + +If the baseUri value is a Level 1 Template URI, the following reserved base URI parameter is available. + +| URI Parameter | Value | +|:----------|:----------| +| version | The value of the root-level version property + +Any other URI template variables appearing in the baseUri MAY be described explicitly within a **baseUriParameters** property at the root of the API definition. The baseUriParameters property has the same structure and semantics as the uriParameters property on a resource property, except that it specifies parameters in the base URI rather than a resource's relative URI. See the section [Template URIs and URI parameters](#template-uris-and-uri-parameters) for information about the uriParameters property. + +The following example RAML API definition uses a Level 1 Template URI as the base URI. + +```yaml +#%RAML 1.0 +title: Salesforce Chatter REST API +version: v28.0 +baseUri: https://na1.salesforce.com/services/data/{version}/chatter +``` + +The following example declares an explicit base URI parameter. + +```yaml +#%RAML 1.0 +title: Amazon S3 REST API +version: 1 +baseUri: https://{bucketName}.s3.amazonaws.com +baseUriParameters: + bucketName: + description: The name of the bucket +``` + +### Protocols + +The OPTIONAL **protocols** property specifies the protocols that an API supports. If the protocols property is not explicitly included, the protocol(s) specified at the baseUri property is (are) used; if the protocols property is specified explicitly, it overrides any protocol specified in the baseUri property. The protocols property MUST be a non-empty array of strings, of values HTTP and/or HTTPS, and is case-insensitive. + +The following is an example of an API endpoint that accepts both HTTP and HTTPS requests. + +```yaml +#%RAML 1.0 +title: Salesforce Chatter REST API +version: v28.0 +protocols: [ HTTP, HTTPS ] +baseUri: https://na1.salesforce.com/services/data/{version}/chatter +``` + +### Default Media Type + +The media types expected from API requests that contain a body, and returned by API responses, can be defaulted by specifying the OPTIONAL **mediaType** property, so they do not need to be specified within every body definition. + +The value of the mediaType property MUST be a media type string conforming to the media type specification in [RFC6838](https://tools.ietf.org/html/rfc6838). + +For any combination of resource, operation, and request or response in the API, if a media type is specified as a key of the body property for that resource and operation and request or response, or if a media type is specified in the mediaType property, the body MUST conform to the specified media type. + +This example shows a RAML snippet for an API that accepts and returns JSON-formatted bodies. If the remainder of this API's specification doesn't explicitly specify another media type, this API only accepts and returns JSON-formatted bodies. + +```yaml +#%RAML 1.0 +title: Stormpath REST API +version: v1 +baseUri: https://api.stormpath.com/{version} +mediaType: application/json +``` + +### Default Security + +The security schemes to be applied to every method of every resource in the API can be defaulted by specifying the OPTIONAL **securedBy** property. Its value is an array of security scheme names. If this property is specified, every method of every resource is protected by the specified security schemes. See section [Applying Security Schemes](#applying-security-schemes) for more information, including how to resolve application of multiple security schemes via inheritance. + +The following example shows an API allowing access through either an OAuth 2.0 security scheme or an OAuth 1.1 security scheme. + +```yaml +#%RAML 1.0 +title: Dropbox API +version: 1 +baseUri: https://api.dropbox.com/{version} +securedBy: [ oauth_2_0, oauth_1_0 ] +securitySchemes: + - oauth_2_0: !include securitySchemes/oauth_2_0.raml + - oauth_1_0: !include securitySchemes/oauth_1_0.raml +``` + +## RAML Data Types + +### Introduction + +RAML 1.0 introduces the notion of data **types**, which provide a concise and powerful way to describe the data in +your API. The data can be in a URI parameter (base or resource URI), a query parameter, a request or response header, +or of course a request or response body. Some types are built in, while custom types may be defined by extending +(inheriting from) the built-in types. In any place where the API expects data, a built-in type may be used to describe +the data, or a type may be extended inline to describe that data. Custom types may also be named and then used +like any built-in type. + +The RAML example below defines a User type with three properties: firstname and lastname of (built-in) type string, +and age of (built-in) type number. This User type is later used to describe the type (schema) for a payload. + +```yaml +#%RAML 1.0 +title: API with Types +types: + User: + type: object + properties: + firstname: string + lastname: string + age: number +/users/{id}: + get: + responses: + 200: + body: + application/json: + type: User +``` + +A RAML type declaration looks somewhat like a JSON schema definition. In fact, RAML types can be used instead of JSON +and XML schemas, or coexist with them. The RAML type syntax, however, is designed to be considerably easier and more +succinct than JSON and XML schemas while retaining their flexibility and expressiveness. Below is a larger example. + +```yaml +#%RAML 1.0 +title: My API with Types +mediaType: application/json +types: + Org: + type: object + properties: + onCall: AlertableAdmin + Head: Manager + Person: + type: object + properties: + firstname: string + lastname: string + title?: string + Phone: + type: string + 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 +/orgs/{orgId}: + get: + responses: + 200: + body: + application/json: + schema: Org +``` + +The example above contains a few advanced features. + +- Optional properties +- [Scalar Type Specialization](#scalar-type-specialization) +- [Inheritance](#inheritance) +- [Arrays](#array-types) +- [Enumerations](#enums) +- [Union Types](#union-types) +- [Maps](#map-types) + +### Overview + +The RAML type system borrows from object oriented programming languages such as Java, +as well as from XSD and JSON Schemas. + +RAML Types in a nutshell: + +- Types are similar to Java classes + - But borrow additional features from JSON Schema, XSD, and more expressive object oriented languages +- You can define Types that inherit from other Types + - Multiple inheritance is allowed +- Types are split into four families: scalars, objects, externals and arrays +- Types can define two types of members: properties and facets. Both are inherited + - Properties are regular object oriented properties + - Facets are special "configurations" that let you specialize types based on characteristics of their values. + For example: minLength, maxLength +- Only object types can declare properties. But all types can declare facets +- The way you specialize a scalar type is by implementing facets ( giving already defined facets a concrete value ) +- The way you specialize an object type is by defining properties + +![Types Hierarchy](images/typesHierarchy.png) + +### Type Declarations + +Types may be declared inline, wherever the API expects data, or in an OPTIONAL **types** property at the root of the API +or in an included library. Types declarations are used to extend built-in types or other custom types, as well as to +add more information to types such as specific examples or annotations. Here are the properties that all type +declarations may have; certain type declarations may have other properties. + +| Property | Description | +|:----------|:----------| +| schema? | Alias for the equivalent "type" property, for compatibility with RAML 0.8. Deprecated - API definitions should use the "type" property, as the "schema" alias for that property name may be removed in a future RAML version. The "type" property allows for XML and JSON schemas. +| type? | A base type which the current type extends, or more generally a type expression. +| example? | An example of an instance of this type. This can be used, e.g., by documentation generators to generate sample values for an object of this type. Cannot be present if the examples property is present. +| examples? | An object containing named examples of instances of this type. This can be used, e.g., by documentation generators to generate sample values for an object of this type. Cannot be present if the examples property is present. See section [Examples](#examples) for more information. +| displayName? | An alternate, human-friendly name for the type +| description? | A longer, human-friendly description of the type +| (<annotationName>)? | Annotations to be applied to this type. Annotations are any property whose key begins with "(" and ends with ")" and whose name (the part between the beginning and ending parentheses) is a declared annotation name. See section on [Annotations](#annotations) for more information. + +### Object Types + +All types that have the built-in object type at the root of their inheritance tree may use the following properties in their type declarations. + +| Property | Description | +|:----------|:----------| +| properties? | The properties that instances of this type may or must have. See section [Properties Declarations](#property-declarations) for more information. +| minProperties? | The minimum number of properties allowed for instances of this type. +| maxProperties? | The maximum number of properties allowed for instances of this type. +| additionalProperties? | JSON schema style syntax for declaring maps. See section [Map Types](#map-types) for more information. +| patternProperties? | JSON schema style syntax for declaring key restricted maps. See section [Map Types](#map-types) for more information. +| discriminator? | Type property name to be used as discriminator, or boolean +| discriminatorValue? | The value of discriminator for the type. + +An object type is created by explicitly inheriting from the built-in type object: + +```yaml +#%RAML 1.0 +title: My API With Types +types: + Person: + type: object + properties: + name: + required: true + type: string +``` + +#### Property Declarations + +Properties of object types are defined using the OPTIONAL **properties** property. The value of the properties property is called a "properties declaration" in this spec. It is an object whose property names specify the allowed property names of the type being declared, and whose property values are either names of types or inline type declarations. + +In addition to the properties available in normal type declarations, properties can specify whether they are required and provide an optional default value. + +Note: +When an Object Type does not contain the "properties" property, the object is assumed to be unconstrained. That means, it may contain any properties of any type. + +| Property | Description | +|:----------|:----------| +| default? | Provides default value for a property. +| required? | Sets if property is optional or not. Default value is `true`. + +The following example declares an object type with two properties: + +```yaml +#%RAML 1.0 +title: My API With Types +types: + Person: + properties: + name: + required: true + type: string + age: + required: false + type: number +``` + +##### Alternative Syntax + +In order to achieve a more "object oriented" experience, a series of shortcuts are available (see [Shortcuts and Syntactic Sugar](#shortcuts-and-syntactic-sugar)). The example below shows a common idiom: + +```yaml +#%RAML 1.0 +title: My API With Types +types: + Person: + properties: + name: string + age?: number +``` + +#### Inheritance + +You can declare object types that inherit from other object types: + +```yaml +#%RAML 1.0 +title: My API With Types +types: + Person: + type: object + properties: + name: + type: string + Employee: + type: Person + properties: + id: + type: string +``` + +You can inherit from more than one type: + +```yaml +#%RAML 1.0 +title: My API With Types +types: + Person: + type: object + properties: + name: string + EmailOwner: + type: object + properties: + email: string + Employee: + type: [ Person, EmailOwner ] + properties: + id: string +``` + +For more details see [Object Type Inheritance](#object-type-inheritance) + +##### Map Types + +Maps (aka Dictionaries) can be declared by creating an object type and declaring a special property called "[]": + +```yaml +#%RAML 1.0 +title: My API With Types +types: + MapOfNumbers: + type: object + properties: + []: + type: number +``` + +Optionally, you can restrict the set of valid keys by specifying a regular expression within the square brackets: + +```yaml +#%RAML 1.0 +title: My API With Types +types: + MapOfNumbers: + type: object + properties: + [a-zA-Z]: + type: number +``` + +To maximize syntax compatibility with JSON Schema you can alternatively use additionalProperties and patternProperties. They will be internally rewritten + +```yaml +#%RAML 1.0 +title: My API With Types + +types: + Person: + type: object + properties: + name: + type: string + Org: + type: object + additionalProperties: Person +``` + +to + +```yaml +#%RAML 1.0 +title: My API With Types +types: + Person: + type: object + properties: + name: + type: string + Org: + properties: + []: + type: Person +``` + +and + +```yaml +#%RAML 1.0 +title: My API With Types +types: + Method: + type: object + properties: + name: + type: string + Resource: + type: object + patternProperties: + "post|get|put": Method +``` + +to + +```yaml +#%RAML 1.0 +title: My API With Types +types: + Method: + type: object + properties: + name: + type: string + Resource: + properties: + [post|get|put]: + type: Method +``` + +### Array Types + +Array Types are declared by using the array qualifier at the end of a Type Expression. If you are defining a top-level Array Type ( like the example below ), you can pass the following additional properties to further restrict its behaviour. + +| Property | Description | +|:----------|:----------| +| uniqueItems? | Boolean value that indicates if items in the array MUST be unique. +| items? | Indicates what type all items in the array inherit from. Can be a reference to an existing type or an inline [type declaration](#type-declaration) +| minItems? | Minimum amount of items in array. Value MUST be equal or greater than 0. Defaults to 0. +| maxItems? | Maximum amount of items in array. Value MUST be equal or greater than 0. Defaults to 2147483647. + +```yaml +#%RAML 1.0 +title: My API With Types +types: + Email: + type: object + properties: + name: + type: string + emails: + type: Email[] + minItems: 1 + uniqueItems: true +``` + +### Scalar Types + +RAML provides a predefined set of Scalar Types. You can "extend" these types and add further restrictions. These restrictions are called "facets" and they exist both for scalar and object types. Each scalar type has a predefined set of facets. + +|Property Name | Description | +|:--------|:------------| +| facets? | When extending from a scalar type you can define new facets (which can then be set to concrete values by subtypes). The value is an object whose properties map facets names to their types. +| enum? | Enumeration of possible values for this primitive type. Cannot be used with the file type. The value is an array containing string representations of possible values, or a single string if there is only one possible value. + +#### Built-in Scalar Types + +RAML defines the following built-in types and additional facets. + +##### String + +A JSON string with the following additional facets: + +|Property Name | Description | +|:--------|:------------| +| pattern? | Regular expression that this string should pass. +| minLength? | Minimum length of the string. Value MUST be equal or greater than 0. Defaults to 0 +| maxLength? | Maximum length of the string. Value MUST be equal or greater than 0. Defaults to 2147483647 + +Example: + +```yaml +types: + Email: + type: string + minLength: 2 + maxLength: 6 +``` + +##### Number + +Any JSON number including [integer](#integer) with the following additional facets: + +|Property Name | Description | +|:--------|:------------| +|minimum? | (applicable only for parameters of type number or integer) The minimum attribute specifies the parameter's minimum value. +|maximum? | (applicable only for parameters of type number or integer) The maximum attribute specifies the parameter's maximum value. +|format? | Identifies the format of the value. The value MUST be one of the following: int32, int64, int, long, float, double, int16, int8 +|multipleOf? | A numeric instance is valid against "multipleOf" if the result of the division of the instance by this keyword's value is an integer. + +Example: + +```yaml +types: + Weight: + type: number + minimum: 3 + maximum: 5 + format: int64 + multipleOf: 4 +``` + +##### Integer + +A subset of JSON numbers that are positive and negative multiples of 1. The integer type inherits its facets from the [number type](#number). + +```yaml +types: + Age: + type: integer + minimum: 3 + maximum: 5 + format: int8 + multipleOf: 1 +``` + +##### Boolean + +A JSON boolean without any additional facets. + +```yaml +types: + IsMarried: + type: boolean +``` + +##### Date + +As defined in [RFC2616](https://www.ietf.org/rfc/rfc2616.txt), all date/time stamps are represented in Greenwich Mean Time (GMT), which for HTTP is equal to UTC (Coordinated Universal Time). This is indicated by including "GMT" as the three-letter abbreviation for the timezone. Example: `Sun, 06 Nov 1994 08:49:37 GMT` + +```yaml +types: + DateOfBirth: + type: date +``` + +##### File + +The ​**file**​ type can be used to constrain the content to send through forms. When it is used in the context of web forms it SHOULD be represented as a valid file upload, and in JSON representation, it SHOULD be represented as a base64 encoded string with a file content. + +|Property Name | Description | +|:--------|:------------| +| fileTypes? | List of valid content-types for the file. The file type `*/*`` should be a valid value. +| minLength? | Specifies the parameter value's minimum number of bytes. Value MUST be equal or greater than 0. Defaults to 0 +| maxLength? | Specifies the parameter value's maximum number of bytes. Value MUST be equal or greater than 0. Defaults to 2147483647 + +#### Enums + +All custom primitive types, except for the file type, can declare an "enum" property. It should contain a set of fixed values. + +Example usage of enums + +```yaml +#%RAML 1.0 +title: My API With Types +types: + country: + type: string + enum: [ usa, rus ] + + sizes: + type: number + enum: [ 1, 2, 3 ] +``` + +#### Custom Scalar Types + +Defining a scalar type is similar to defining a custom object type in that you "specialize" a parent type. Here's a custom scalar type that "specializes" the number type and restricts one of its facets (minimum): + +```yaml +#%RAML 1.0 +title: My API With Types +types: + positiveNumber: + type: number + minimum: 1 +``` + +For convenience, you may specialize the built-in primitive types ( string, number, etc ). However, if you don't wish your custom scalar type to inherit the predefined facets of built-in types you can inherit directly from the "scalar" type. + +You can define your own facets: + +```yaml +#%RAML 1.0 +title: My API With Types +types: + Date: + type: string + facets: + format: string + + MyDate: + type: Date + format: 'dd.mm.yyyy' +``` + +### Type Expressions + +So far we have only used simple type identifiers to refer to other Types (ex: string, object, Person). Type Expressions provide a powerful way of referring to, and even defining, types. Type Expressions can be used wherever a type is expected. +The simplest Type Expression is just the name of a type. But Type expressions also allow you to express Type Unions, Arrays, and maps amongst other things. + +|Expression | Description | +|:--------|:------------| +| `Person` | The simplest type expression: A single Type +| `Person[]` | An array of Person objects +| `string[]` | An array of string scalars +| `string[][]` | A bi-dimensional array of string scalars +| `string \| Person` | Union type made of members of string OR Person +| `(string \| Person)[]` | An array of the above type +| `number{}` | A map/dictionary of numbers + +Type Expressions can be used wherever a Type is expected: + +```yaml +#%RAML 1.0 +title: My API With Types + +types: + Phone: + type: object + properties: + manufacturer: + type: string + numberOfSIMCards: + type: number + Notebook: + type: object + properties: + manufacturer: + type: string + numberOfUSBPorts: + type: number + Person: + type: object + properties: + devices: ( Phone | Notebook )[] + reports: Person[] +``` + +You can even "extend" from a type expression. For example: + +```yaml +#%RAML 1.0 +title: My API With Types +types: + Phone: + type: object + properties: + manufacturer: + type: string + numberOfSIMCards: + type: number + Notebook: + type: object + properties: + manufacturer: + type: string + numberOfUSBPorts: + type: number + Devices: + type: ( Phone | Notebook )[] +``` + +The example above is actually declaring a "Type Alias", which gives a more readable name ( Devices ) to a type defined via a complex type expression ( in this case an array of a union of the types Phone and Notebook ). You can use this technique to give simple names to complex types. Type Aliases can also hold extra properties. For example a description and annotations. + +#### Grammar + +Type expressions are composed of names of built-in or custom types and certain symbols, as follows: + +| Expression | Description | Examples +|:----------|:----------|:---------| +| | Type name (the basic building block of a type expression) | `number:` a built-in type

    `Person:` a custom type +| (type expression) | Parentheses may be used to disambiguate the expression to which an operator applies. | `Person | Animal[]`

    `( Person | Animal )[]` +| (type expression)[] | Array operator: a unary postfix operator placed after another type expression (enclosed in parentheses, as needed) and indicating that the resulting type is an array of instances of that type expression. | `string[]:` an array of strings

    `Person[][]:` an array of arrays of Person instances +| (type expression 1) | (type expression 2) | Union operator: an infix operator indicating that the resulting type may be either of type expression 1 or of type expression 2. Multiple union operators may be combined between pairs of type expressions. | `string | number:` either a string or a number

    `X | Y | Z`: either an X or a Y or a Z

    `(Manager | Admin)[]:` an array whose members consist of Manager or Admin instances

    `Manager[] | Admin[]:` an array of Manager instances or an array of Admin instances. + +There are additional constraints on type expressions when used to define inheritance. They are described at [Rules of Inheritance](#inheritance-and-specialization). For example, the following is not valid (you cannot add properties to a union type). + + +```yaml +#%RAML 1.0 +title: My API With Types +types: + Phone: + type: object + properties: + manufacturer: + type: string + numberOfSIMCards: + type: number + Notebook: + type: object + properties: + manufacturer: + type: string + numberOfUSBPorts: + type: number + Device: + type: Phone | Notebook + properties: + weight: number +``` + +### Union Types + +Union Types are declared using pipes (|) in your type expressions. Union Types are useful to model common scenarios in JSON based applications, for example an array containing objects which can be instances of more than one type. +If you are defining Type Alias for a Union Type ( like the example below ), you can also specify the discriminator property. See [Runtime Polymorphism (Discriminators)](#runtime-polymorphism-discriminators-). + +|Property | Description | +|:--------|:------------| +| discriminator? | Type property name to be used as a discriminator or boolean + +```yaml +#%RAML 1.0 +title: My API With Types +types: + Phone: + type: object + properties: + manufacturer: + type: string + numberOfSIMCards: + type: number + kind: string + Notebook: + type: object + properties: + manufacturer: + type: string + numberOfUSBPorts: + type: number + kind: string + Device: + type: Phone | Notebook + discriminator: kind +``` + +### Inheritance and Specialization + +When declaring a RAML Type you are always inheriting from, or specializing, an existing type. The general syntax for inheritance is: + +```yaml +MyType: + type: ParentTypeExpression +``` + +Depending on the value of ParentTypeExpression, though, the meaning of inheritance will change. It is important to understand the differences: + +```yaml +#%RAML 1.0 +title: My API With Types +types: + Person: + type: object + properties: + name: string + MyType: + type: Person + properties: + x: string +``` + +```yaml +#%RAML 1.0 +title: My API With Types +types: + Person: + type: object + properties: + name: string + Auditable: + type: object + properties: + personalId: number + Employee: + type: [Person, Auditable] + properties: + positionName: string +``` + +```yaml +#%RAML 1.0 +title: My API With Types +types: + MyType: + type: number + minimum: 0 +``` + +```yaml +#%RAML 1.0 +title: My API With Types +types: + Person: + type: object + properties: + name: string + MyType: + type: Person[] + uniqueItems: true +``` + +```yaml +#%RAML 1.0 +title: My API With Types +types: + Phone: + type: object + properties: + someNumberProperty: + type: number + Notebook: + type: object + properties: + someStringProperty: + type: string + MyType: + type: Notebook | Phone +``` + +Each Inheritance type is explained in detail in the following sections: + +#### Object Type Inheritance + +Object inheritance works like normal Object Oriented inheritance. A subtype inherits all the properties of its parent type. + +```yaml +#%RAML 1.0 +title: My API With Types +types: + B: + type: object + A: + type: B +``` + +##### Property Overrides + +Subtypes can override properties defined in parent types. There are two restrictions: + +If a property is required in the parent, it cannot be made optional in the subtype +The type of an already defined property can only be changed to a narrower type ( a type that specializes the parent type ) + +##### Multiple Inheritance + +RAML Types support multiple inheritance for object types. This is achieved by passing a sequence of types: + +```yaml +#%RAML 1.0 +title: My API With Types +types: + A: + type: object + B: + type: object + C: + type: [ A, B ] +``` + +Note: Multiple inheritance is only allowed if all Type Expressions are simple object Types. See [Inheritance Restrictions](#inheritance-restrictions). + +##### Property Overrides + +If multiple parent types define a property with the same name: + +* The property will be required if at least one of the declarations are required +* The type of the property will be the narrowest type + + +#### Scalar Type Specialization + +If the type expression is a simple scalar type, specialization is achieved by setting values for previously defined facets. + +#### Array Type Specialization + +If the outer type of the type expression is an array you can set a value for the available array type facets: + +| Property | Description | +|:----------|:----------| +| uniqueItems? | Boolean value that indicates if items in the array MUST be unique. +| items? | Indicates what type all items in the array inherit from. Can be a reference to an existing type or an inline [type declaration](#type-declaration) +| minItems? | Minimum amount of items in array. Value MUST be equal or greater than 0. Defaults to 0. +| maxItems? | Maximum amount of items in array. Value MUST be equal or greater than 0. Defaults to 2147483647. + +The example below defines an array of numbers and sets its "uniqueItems" facet to true. + +```yaml +#%RAML 1.0 +title: My API With Types +types: + NumberSet: + type: number[] + uniqueItems: true +``` +#### External Types + +The RAML 1.0 Type system allows seamless integration of json/xsd schemas as type definitions. This is achieved by implicitly converting references to json/xsd schemas to subtypes of the **external** built-in type. + +These types can then be used freely within the RAML Type system as normal types except for one restriction: You cannot inherit from them. + +The following type declarations create subclasses of external types. + +```yaml +#%RAML 1.0 +title: My API With Types +types: + Person: + type: !include schemas/PersonSchema.json +``` + +```yaml +#%RAML 1.0 +title: My API With Types +types: + Person: !include schemas/PersonSchema.xsd +``` + +##### External Types and Inheritance + +External types cannot participate in type inheritance or specialization. In other words: You cannot define sub-types of external types that declare new properties or set facets. You can, however, create simple type wrappers that add metadata, examples and a description. + +##### Validation of instances + +Validation of instances of external types is delegated to standard json/xsd schema validation. To this end objects are automatically converted if needed to JSON or XML before validation. In the case of JSON this transformation is straightforward. In the case of XML serialization, the canonical XML serialization algorithm is used. + +#### Inheritance Restrictions + +* You cannot inherit from types of different kind at the same moment ( kinds are: union types, array types, object types, scalar types ) +* You cannot inherit from types extending union types ( ex: you cannot extend from `Pet` if `Pet = Dog | Cat` ) +* You cannot inherit from multiple primitive types ( Multiple inheritance is only allowed for object types ) +* You cannot inherit from a type that extends Array type ( this will result in simple type aliasing/wrapping ) +* Facets are always inherited +* You can fix a previously defined facet to a value if the facet is defined on a superclass +* Properties are only allowed on object types +* You cannot create cyclic dependencies when inheriting +* You cannot inherit from "external" types + +### Shortcuts and Syntactic Sugar + +RAML Types are meant to be easy to read and write. To make the syntax more concise and in line with traditional object oriented programming languages, as well as familiar for developers who have used JSON schema before, the following shortcuts have been defined: + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
    ExampleExpanded Equivalent
    Inline type expression gets expanded to a proper type declaration
    Email: string
    Email: 
      type: string
    `string` is default type when nothing else defined 
    Email:
    Email:
      type: string
    `object` is default type when `properties` is defined
    Person:
      properties:
    Person:
      type: object
      properties:
    Shorthand for Optional Property Syntax (?)
    Person:
      properties:
        nick?: string
    Person:
      type: object
      properties:
        nick:
          type: string
          required: false
    Inline Map
    Person:
      properties:
        pets: Pet{}
    Person:
      properties:
        pets: PetMap
    PetMap:
      properties:
        []: Pet
    + +### Inline Type Declarations + +You can declare inline/anonymous types everywhere a type can be referenced other than in a Type Expression. + +```yaml +#%RAML 1.0 +title: My API With Types +/users/{id}: + get: + responses: + 200: + body: + application/json: + type: object + properties: + firstname: + type: string + lastname: + type: string + age: + type: number +``` + +### Runtime Polymorphism (Discriminators) + +When payloads contain ambiguous types ( achieved via unions or inheritance ) it is often impossible to discriminate the concrete type of an individual object at runtime ( for example when deserializing the payload into a statically typed language ) + +RAML provides a pragmatic solution to this problem: You can store the actual type of an object as a string. + +To indicate that a certain family of types is using the "discriminator" convention, simply set it to true on a common supertype. + +```yaml +#%RAML 1.0 +title: My API With Types +types: + Person: + type: object + discriminator: true + properties: + name: string + Employee: + type: Person + properties: + employeeId: string + User: + type: Person + properties: + userId: string +``` + +```yaml +#%RAML 1.0 +data: + - name: A User + userId: 111 + discriminator: User + - name: An Employee + employeeId: 222 + discriminator: Employee +``` + +When a type belongs to a family of types that has the discriminator facet set to true, then instances of such class must have a discriminator property holding the name of the class. You can customize the name of the discriminator property by using a string value instead of a boolean value. + +Here's the same example, but this time we customize the property that holds the type name: + +```yaml +#%RAML 1.0 +title: My API With Types +types: + Person: + type: object + discriminator: kind + properties: + kind: string + name: string + Employee: + type: Person + properties: + employeeId: string + User: + type: Person + properties: + userId: string +``` + +```yaml +#%RAML 1.0 +data: + - name: A User + userId: 111 + kind: User + - name: An Employee + employeeId: 222 + kind: Employee +``` + +You can also override the value of the discriminator for each individual concrete class. In the following example we will replace the default type discriminator values by their lowercase versions: + +```yaml +#%RAML 1.0 +title: My API With Types +types: + Person: + type: object + discriminator: kind + properties: + name: string + kind: string + Employee: + type: Person + discriminatorValue: employee + properties: + employeeId: string + User: + type: Person + discriminatorValue: person + properties: + userId: string +``` + +```yaml +#%RAML 1.0 +data: + - name: A User + userId: 111 + kind: user + - name: An Employee + employeeId: 222 + kind: employee +``` + +When defining a discriminator for a family of types, all member types must be object types and have the discriminator property present ( or, if the name has been customized, the corresponding custom property ). This property must be of type string. + +```yaml +#%RAML 1.0 +title: My API With Types +types: + X: + type: object + properties: + discriminator: string + Y: + type: object + properties: + discriminator: string + Z: + type: object + properties: + discriminator: string + XYZ: + type: X | Y | Z + discriminator: true +``` + +### Examples + +It is highly RECOMMENDED that API documentation include a rich selection of examples. + +The OPTIONAL **example** property may be used to attach an example of a type's instance to the type declaration. Its value is an instance of the type. + +The OPTIONAL **examples** property may be used to attach multiple examples. Its value can be + +1. an object whose property names are to be interpreted as names of examples, and whose values are objects that describe each example +2. an array of objects that describe each example + +Each example object has the following properties: + +|Property | Description | +|:--------|:------------| +| displayName? | An alternate, human-friendly name for the example +| description? | A longer, human-friendly description of the example +| (<annotationName>)? | Annotations to be applied to this example. Annotations are any property whose key begins with "(" and ends with ")" and whose name (the part between the beginning and ending parentheses) is a declared annotation name. See section [Annotations](#annotations) for more information. +| content | The example itself +| strict? | By default, examples are validated against any type declaration. Set this to false to allow examples that need not validate. + +The example and examples properties are mutually-exclusive in any given type declaration. + +The following illustrates usage of both example and examples properties. + +```yaml +#%RAML 1.0 +title: API with Examples +types: + User: + type: object + properties: + name: string + lastname: string + example: + name: Bob + lastname: Marley + Org: + type: object + properties: + name: string + address?: string + examples: + - content: + name: Acme + - content: + name: Software Corp + address: 35 Central Street + Org_alt: + type: object + properties: + name: string + address?: string + examples: + acme: + content: + name: Acme + softwareCorp: + content: + name: Software Corp + address: 35 Central Street +``` + +RAML Type declarations with examples + +### Using Types in RAML + +* Types may be used in several positions: + * Body ( JSON ) + * Body ( XML ) + * Body ( Web Form ) + * Headers + * Query Parameters + * URI Parameters +* Serialization rules depend on both the type and the position in which it is used +* When declaring a custom value type ( extending the "value" built-in type ) it will have "string" as its default serialization target. +* When extending one of the built-in types, your type will inherit the serialization target + +## Resources and Nested Resources + +Resources are identified by their relative URI, which MUST begin with a slash ("/"). Every property whose key begins with a slash, and is either at the root of the API definition or is the child property of a resource property, is such a resource property. + +A resource defined as a root-level property is called a top-level resource. Its property's key is the resource's URI relative to the baseUri (if any). A resource defined as a child property of another resource is called a nested resource, and its property's key is its URI relative to its parent resource's URI. + +This example shows an API definition with one top-level resource, /gists, and one nested resource, /public. + +```yaml +#%RAML 1.0 +title: GitHub API +version: v3 +baseUri: https://api.github.com +/gists: + displayName: Gists + /public: + displayName: Public Gists +``` + +The key of a resource property, i.e. its relative URI, MAY consist of multiple URI path fragments separated by slashes; e.g. /bom/items may indicate the collection of items in a bill of materials as a single resource. However, if the individual URI path fragments are themselves resources, the API definition SHOULD use nested resources to describe this structure; e.g. if /bom is itself a resource then /items should be a nested resource of /bom, vs using /bom/items as a non-nested resource. + +Absolute URIs are not explicitly specified. They are computed by starting with the baseUri and appending the relative URI of the top-level resource, and then successively appending the relative URI values for each nested resource until the target resource is reached. + +Taking the previous example, the absolute URI of the public gists resource is formed as follows. + +``` + "https://api.github.com" <--- baseUri + + + "/gists" <--- gists resource relative URI + + + "/public" <--- public gists resource relative URI + = +"https://api.github.com/gists/public" <--- public gists absolute URI +``` + +A nested resource can itself have a child (nested) resource, creating a multiply-nested resource. In the following example, /user is a top-level resource that has no children; /users is a top-level resource that has a nested resource, /{userId}; and the nested resource, /{userId}, has three nested resources, /followers, /following, and /keys. + + +```yaml +#%RAML 1.0 +title: GitHub API +version: v3 +baseUri: https://api.github.com +/user: +/users: + /{userId}: + uriParameters: + userId: + type: integer + /followers: + /following: + /keys: + /{keyId}: + uriParameters: + keyId: + type: integer +``` + +The computed absolute URIs for the resources, in the same order as their resource declarations, are as follows. + +``` +https://api.github.com/user +https://api.github.com/users +https://api.github.com/users/{userId} +https://api.github.com/users/{userId}/followers +https://api.github.com/users/{userId}/following +https://api.github.com/users/{userId}/keys +https://api.github.com/users/{userId}/keys/{keyId} +``` + +The value of a resource property is an object whose properties are described in the following table. + +|Property | Description | +|:--------|:------------| +| displayName? | An alternate, human-friendly name for the resource. +| description? | A longer, human-friendly description of the resource. +| (<annotationName>)? | Annotations to be applied to this resource. Annotations are any property whose key begins with "(" and ends with ")" and whose name (the part between the beginning and ending parentheses) is a declared annotation name. See section [Annotations](#annotations). +| get?
    patch?
    put?
    post?
    delete?
    options?
    head? | Object describing the method. See section [Methods](#methods) for more information. +| is? | A list of the traits to apply to all methods declared (implicitly or explicitly) for this resource. See section [Applying Resource Types and Traits](#applying-resource-types-and-traits) for more information. Individual methods may override this declaration +| type? | The resource type which this resource inherits. See section [Applying Resource Types and Traits](#applying-resource-types-and-traits) for more information. +| securedBy? | The security schemes that apply to all methods declared (implicitly or explicitly) for this resource. See section [Applying Security Schemes](#applying-security-schemes) for more information. +| uriParameters? | Detailed information about any URI parameters of this resource +| /<relativeUri> | A nested resource is identified as any property whose name begins with a slash ("/") and is therefore treated as a relative URI. + +### Resource Display Name + +The OPTIONAL **displayName** property provides a friendly name to the resource and can be used by documentation generation tools. If the displayName property is not defined for a resource, documentation tools SHOULD refer to the resource by its property key (i.e. its relative URI, e.g., /jobs), which acts as the resource's name. + +### Resource Description + +The OPTIONAL **description** property can be used to provide a longer description of the resource. It is RECOMMENDED that all resources provide such a description. + +### Template URIs and URI Parameters + +Template URIs containing URI parameters can be used to define a resource's relative URI when it contains variable elements. The following example shows a top-level resource with a key /jobs and a nested resource with a key /{jobId}. + +```yaml +#%RAML 1.0 +title: ZEncoder API +version: v2 +baseUri: https://app.zencoder.com/api/{version} +/jobs: # its fully-resolved URI is https://app.zencoder.com/api/{version}/jobs + description: A collection of jobs + /{jobId}: # its fully-resolved URI is https://app.zencoder.com/api/{version}/jobs/{jobId} + description: A specific job, a member of the jobs collection +``` + +The OPTIONAL **uriParameters** property is used to explicitly specify URI parameters in a template URI. The value of the uriParameters property is an object, specifically a [properties declaration](#property-declarations), as is the value of the properties object of a type declaration. Each property in this declaration object is referred to as a **URI parameter declaration**. The name of each such property corresponds to the name of a parameter in the template URI, while its value specifies the URI parameter's type, as the name of a type or an inline type declaration. + +Every property in a uriParameters declaration MUST correspond exactly to the name of a URI parameter in the resource's relative URI. But not every URI parameter in the resource's relative URI must be explicitly specified in the uriParameters property. Every parameter in the relative URI not specified in the uriParameters property MUST still be treated as a URI parameter, of type string, and required. + +Just as is the case for [the baseUriParameters root property](#base-uri-and-base-uri-parameters), the version parameter is a reserved parameter name in the uriParameters properties declaration, with a value corresponding to the value of the version root-level property. + +The example below shows two top-level resources (/user and /users) and a nested resource specified by its template URI, /{userId}. The URI parameter userId is explicitly declared, and given a description and an integer type. + +```yaml +#%RAML 1.0 +title: GitHub API +version: v3 +baseUri: https://api.github.com +/user: + description: The currently authenticated User +/users: + description: All users + /{userId}: + description: A specific user + uriParameters: + userId: + description: The id of the user + type: integer +``` + +If a URI parameter declaration specifies an array or object type for the value of the header, or if it specifies a union type of non-scalar types, then processors MUST default to treating the format of the URI parameter value as JSON in applying the type to instances of that URI parameter. They MAY allow other treatments based on annotations. + +If a URI parameter declaration specifies a non-string scalar type for the value of the header, the standard serialization rules for types MUST be invoked in applying the type to instances of that URI parameter. + +The values matched by URI parameters MUST NOT contain slash (/) characters, in order to avoid ambiguous matching. In the example above, a URI (relative to the baseUri) of /jobs/123 matches the /{jobId} resource nested within the /jobs resource, but a URI of /jobs/123/x does not match any of those resources. + +In the example below, the top-level resource has two URI parameters, folderId and fileId. + +```yaml +#%RAML 1.0 +title: Flat Filesystem API +version: v1 +/files: + description: A collection of all files + /folder_{folderId}-file_{fileId}: + description: An item in the collection of all files +``` + +Although URI parameters can be explicitly specified to be optional, they SHOULD be required when they are surrounded directly by slashes ("/"), that is, when they constitute complete URI path fragments, e.g. .../{objectId}/.... It usually makes little sense to allow a URI to contain adjacent slashes with no characters between them, e.g. ...//.... Hence, a URI parameter should only be specified as optional when it appears adjacent to other text; e.g., /people/~{fieldSelectors} indicates that the {fieldSelectors} URI parameter can be blank, and therefore optional, indicating that /people/~ is a valid relative URI. + +A special URI parameter, **ext**, is a reserved parameter. It may or may not be specified explicitly in a uriParameters property, but its meaning is reserved: it is used by a client to specify that the body of the request or response be of the associated media type. + +|URI Parameter | Value | +|:--------|:------------| +| ext | The desired media type of the request or response body + +By convention, a value for the ext parameter of .json is equivalent to an Accept header of application/json, and a value of .xml is equivalent to an Accept header of text/xml. By employing the ext parameter, clients may specify the media type of a request or response via the URI rather than via the Accept HTTP header. For example, in the following example, the /users resource may be requested as application/json or text/xml: + +```yaml +#%RAML 1.0 +title: API Using media type in the URL +version: v1 +/users{ext}: + uriParameters: + ext: + enum: [ .json, .xml ] + description: Use .json to specify application/json or .xml to specify text/xml +``` + +## Methods + +In a RESTful API, methods are operations that are performed on a resource. The OPTIONAL properties **get**, **patch**, **put**, **post**, **delete**, **head**, and **options** of a resource define its methods; these correspond to the HTTP methods defined in the HTTP version 1.1 specification [RFC2616](https://www.ietf.org/rfc/rfc2616.txt) and its extension, [RFC5789](https://tools.ietf.org/html/rfc5789). The value of any of these method properties is an object whose properties are described in the following table. + +|Property | Description | +|:--------|:------------| +| displayName? | An alternate, human-friendly name for the method (in the resource's context). +| description? | A longer, human-friendly description of the method (in the resource's context). +| (<annotationName>)? | Annotations to be applied to this method. Annotations are any property whose key begins with "(" and ends with ")" and whose name (the part between the beginning and ending parentheses) is a declared annotation name. See section [Annotations](#annotation) for more information. +| queryParameters? | Detailed information about any query parameters needed by this method. Mutually exclusive with queryString. +| headers? | Detailed information about any request headers needed by this method. +| queryString? | Specifies the query string needed by this method. Mutually exclusive with queryParameters. +| responses? | Information about the expected responses to a request. +| body? | Some methods admit request bodies, which are described by this property. +| protocols? | A method can override the protocols specified in the resource or at the API root, by employing this property. See section [Method-level Protocols](#method-level-protocols) for more information. +| is? | A list of the traits to apply to this method. See [Applying Resource Types and Traits](#applying-resource-types-and-traits) section. +| securedBy? | The security schemes that apply to this method. See section [Applying Security Schemes](#applying-security-schemes) for more information. + +### Method-level Display Name + +The OPTIONAL **displayName** property provides a friendly name for the method and can be used by documentation generation tools. If the displayName property is not defined for a method, documentation tools SHOULD refer to the resource by its property key, which acts as the method's name. + +### Method-level Description + +The OPTIONAL **description** property describes the operation of the method on the resource. Its value is a markdown string. It is RECOMMENDED that all methods provide such a description. + +The following example shows a resource, /jobs, with post and get methods declared. + +```yaml +#%RAML 1.0 +title: ZEncoder API +version: v2 +baseUri: https://app.zencoder.com/api/{version} +/jobs: + post: + description: Create a *new* job + get: + description: List some or all jobs +``` + +### Headers + +An API's methods may support or require various HTTP headers. The OPTIONAL **headers** property is used to explicitly specify those headers. The value of the headers property is an object, specifically a [properties declaration](#property-declarations), as is the value of the properties object of a type declaration. Each property in this declaration object is referred to as a header **declaration**. The name of each such property specifies an allowed header name, while its value specifies the header value's type, as the name of a type or an inline type declaration. + +The following simple example shows a post method with a single HTTP header named Zencoder-Api-Key of (implied) string type. + +```yaml +#%RAML 1.0 +title: ZEncoder API +version: v2 +baseUri: https://app.zencoder.com/api/{version} +/jobs: + post: + description: Create a job + headers: + Zencoder-Api-Key: + description: The API key needed to create a new job +``` + +If a header declaration specifies an array type for the value of the header, processors MUST interpret this as allowing multiple instances of that header in the request or response, as appropriate. In such a case, the underlying type of the array -- namely, the type of the elements of the array -- MUST be applied as the type of the value of instances of this header. + +If a header declaration specifies a non-array type for the value of the header (or doesn't specify a type, which is equivalent to specifying a string type), processors MUST interpret this as disallowing multiple instances of that header in the request or response, as appropriate. + +If a header declaration specifies an object type or a union of non-scalar types for the value of the header, or if it specifies an array type for the value of the header and the underlying type of the array is an object or array type or a union of non-scalar types, then validation is not defined by RAML; processors MAY default to treating the format of the header value as JSON in applying the type to instances of that header, or they MAY allow other treatments based on annotations. + +Note that some headers may also be added by the intermediate client- and server-side systems such as a browser or a proxy. + +The following example illustrates inheriting headers from a trait, allowing multiple instances of a header, specifying examples, and overriding them when they're applied to a method and a resource. + +```yaml +#%RAML 1.0 +title: Example with headers +traits: + chargeable: + headers: + X-Dept: + type: array + description: | + A department code to be charged. + Multiple such headers are allowed. + items: + pattern: ^\d+\-\w+$ + example: 230-OCTO + traceable: + headers: + X-Tracker: + description: A code to track API calls end to end + pattern: ^\w{16}$ + example: abcdefghijklmnop +/users: + get: + is: [ chargeable, traceable ] + description: | + The HTTP interaction will look like + + GET /users HTTP/1.1 + X-Dept: 18-FINANCE + X-Dept: 200-MISC + X-Tracker: gfr456d03ygh38s2 + headers: + X-Dept: + example: [ 18-FINANCE, 200-MISC ] + X-Tracker: + example: gfr456d03ygh38s2 +``` + +### Query Strings and Query Parameters + +An API's methods may support or require a query string in the URL on which they are invoked. The query string in a URL is defined in [RFC3986](https://www.ietf.org/rfc/rfc3986.txt) as the part of the URL following the question mark separator ("?") and preceding any fragment ("#") separator. The query string may be specified either by the OPTIONAL **queryString** property or by the OPTIONAL **queryParameters** property. The queryString and queryParameters properties are mutually exclusive: processors MUST NOT allow both to be specified (explicitly or implicitly) on the same method of the same resource. + +#### The Query String as a Whole + +The queryString property is used to specify the query string as a whole, rather than as name-value pairs. Its value is either the name of a type or an inline type declaration. + +If the queryString property specifies a non-scalar type or a union of non-scalar types, then processors MUST default to treating the format of the query string as JSON in applying the type to instances of that query string. They MAY allow other treatments based on annotations. + +The following example shows a get method with a query string that is expected to be in JSON format. + +```yaml +#%RAML 1.0 +title: Example with query string +/users: + get: + queryString: + description: We filter based on a JSON-formatted query string + type: !include schemas/usersFilter.json +``` + +#### Query Parameters in a Query String + +The queryParameters property is used to specify the set of query parameters from which the query string is composed. Processors MUST regard the query string as a set of query parameters according to the URL encoding format when applying the restrictions in the API definition. The value of the queryParameters property is an object, specifically a [properties declaration](#property-declarations), as is the value of the properties object of a type declaration. Each property in this declaration object is referred to as a **query parameter declaration**. The name of each such property specifies an allowed query parameter name, while its value specifies the query parameter value's type, as the name of a type or an inline type declaration. + +If a query parameter declaration specifies an array type for the value of the query parameter, processors MUST interpret this as allowing multiple instances of that query parameter in the request or response, as appropriate. In such a case, the underlying type of the array -- namely, the type of the elements of the array -- MUST be applied as the type of the value of instances of this query parameter. + +If a query parameter declaration specifies a non-array type for the value of the query parameter (or doesn't specify a type, which is equivalent to specifying a string type), processors MUST interpret this as disallowing multiple instances of that query parameter in the request. + +If a query parameter declaration specifies an object type or a union of non-scalar types for the value of the query parameter, or if it specifies an array type for the value of the query parameter and the underlying type of the array is an object type or union of non-scalar types, then processors MUST default to treating the format of the query parameter value as JSON in applying the type to instances of that query parameter. They MAY allow other treatments based on annotations. + +If a query parameter declaration specifies a non-string scalar type or union of non-string scalar types for the value of the query parameter, or if it specifies an array type for the value of the query parameter and the underlying type of the array is a non-string scalar type or union of non-string scalar types, the standard serialization rules for types MUST be invoked in applying the type to instances of that query parameter. + +The following example shows a get method that uses HTTP query parameters; it will be sent to https://api.github.com/v3/users?page=1&per_page=50 (assuming the example values are used). + + +```yaml +#%RAML 1.0 +title: GitHub API +version: v3 +baseUri: https://api.github.com/{version} +/users: + get: + description: Get a list of users + queryParameters: + page: + description: Specify the page that you want to retrieve + type: integer + required: true + example: 1 + per_page: + description: Specify the amount of items that will be retrieved per page + type: integer + minimum: 10 + maximum: 200 + default: 30 + example: 50 +``` + +### Method-level Protocols + +A method can explicitly set the OPTIONAL **protocols** property to specify the protocol(s) used to invoke it, thereby overriding the protocols set elsewhere, e.g. in the baseUri or the root-level **properties** property. + +In the following example, the get method is accessible through both HTTP and HTTPS, while the rest of the API requires HTTPS. + +```yaml +#%RAML 1.0 +title: Twitter API +version: 1.1 +baseUri: https://api.twitter.com/{version} +/search/tweets.json: + description: Search all tweets + get: + description: Returns a collection of relevant Tweets matching a specified query + protocols: [ HTTP, HTTPS ] +``` + +### Bodies + +The HTTP request **body** for a method is specified using the OPTIONAL body property. For example, to create a resource using a POST or PUT, the body of the request would usually include the details of the resource to be created. + +The value of the body property is termed a **body declaration**. The body declaration is an object whose property names are the valid media types of the request body and whose property values are the corresponding data type declaration or data type name describing the request body. If a default media type has been declared at the root of the API via the mediaType property, then the body declaration may alternatively be directly the data type declaration or data type name describing the request body for that media type. + +In the first case above, when the property names represent media types, each property name MUST be a media type string conforming to the media type specification in [RFC6838](#https://tools.ietf.org/html/rfc6838). + +The following example illustrates various combinations of both default and non-default media types, and both data type declarations and references. + +```yaml +#%RAML 1.0 +title: Example of request bodies +mediaType: application/json +types: + User: + properties: + firstName: + lastName: +/users: + post: + body: + type: User +/groups: + post: + body: + application/json: + properties: + groupName: + deptCode: + type: number + text/xml: + type: !include schemas/group.xsd +``` + +## Responses + +The resources and methods sections of this document have so far described HTTP requests. This section describes the HTTP responses to method invocations on resources. + +The OPTIONAL **responses** property of a method on a resource describes the possible responses to invoking that method on that resource. Its value is an object whose property names are the possible HTTP status codes for that method on that resource, and whose property values describe the corresponding responses. Each such value is termed a **response declaration**. + +Note that the properties of the responses object are often numeric, e.g. 200 or 204. Processors MUST treat these numeric keys as string keys for all purposes. For example, '200' and 200 MUST be treated as equivalent property keys and therefore not both would be allowed simultaneously since they would constitute duplicate properties. + +The value of a response declaration is an object that may contain any of the following properties. + +|Property | Description | +|:--------|:------------| +| displayName? | An alternate, human-friendly name for the response +| description? | A longer, human-friendly description of the response +| (<annotationName>) | Annotations to be applied to this response. Annotations are any property whose key begins with "(" and ends with ")" and whose name (the part between the beginning and ending parentheses) is a declared annotation name. See section [Annotations](#annotations) for more information. +| headers? | Detailed information about any response headers returned by this method +| body? | The body of the response + +The OPTIONAL properties **displayName**, **description**, **headers**, **body**, and **annotations** have the same syntax and semantics as they do for [method declarations](methods), but applied to HTTP responses rather than HTTP requests. + +The following example illustrates some possible responses. + +```yaml +#%RAML 1.0 +title: Example with responses +mediaType: application/json +types: + Invoice: + properties: + amount: + type: number + minimum: 0 + vendorName: +/invoices: + get: + responses: + 200: + body: + type: Invoice + properties: + id: number + post: + body: + type: Invoice + responses: + 201: + headers: + Location: + example: /invoices/45612 + body: + application/json: + type: !include schemas/invoice.json + text/xml: + type: !include schemas/invoice.xsd + 422: + body: + properties: + error: + example: + error: Amount cannot be negative +``` + +## Resource Types and Traits + +There are many advantages to reusing patterns across multiple resources and methods. For example, after defining a collection-type resource's characteristics, that definition can be applied to multiple resources. This use of patterns encourages consistency and reduces complexity for both servers and clients. + +Moreover, resource and method declarations are frequently repetitive. For example, an API that requires OAuth authentication might require an X-Access-Token header for all methods across all resources. For many reasons it may be preferable to define such a pattern in a single place and apply it consistently everywhere. + +A resource type is a partial resource definition that, like a resource, can specify security schemes and methods and other properties. Resources that use a resource type inherit its properties. A resource type can also use, and thus inherit from, another resource type. Resource types and resources are related through an inheritance chain pattern. + +A trait is a partial method definition that, like a method, can provide method-level properties such as description, headers, query string parameters, and responses. Methods that use one or more traits inherit those traits' properties. Resources and resource types can also use, and thus inherit from, one or more traits, which then apply to all of their methods. Traits are related to methods through a mixing pattern. + +Resources may specify the resource type from which they inherit using the type property. The resource type may be defined inline as the value of the type property (directly or via an !include), or the value of the type property may be the name of a resource type defined within the root-level resourceTypes property or in a library. + +Similarly, methods may specify one or more traits from which they inherit using the is property. Its value is an array of traits. A resource may also use this property, in which case the array of traits is applied to all its methods. Each trait element in that array may be defined inline (directly or via an !include), or it may be the name of a trait defined within the root-level traits property or in a library. + +Resource type definitions MUST NOT incorporate nested resources; they cannot be used to generate nested resources when they are applied to a resource, and they do not apply to its existing nested resources. + +### Declaration + +Resource types may be declared via the OPTIONAL **resourceTypes** property at the root of the API definition. The value of this property is an object whose property names become names of resource types that can be referenced throughout the API, and whose property values are resource type declarations. Resource types may also be declared inline, anonymously. + +Similarly, traits may be declared via the OPTIONAL **traits** property at the root of the API definition. The value of this property is an object whose property names become names of traits that can be referenced throughout the API, and whose property values are trait declarations. Traits may also be declared inline, anonymously. + +Resource type and trait declarations can have the following properties, in addition to all the properties that resources and methods may have, respectively (except that resource type declarations MUST NOT have nested resource properties). + +| Property | Definition | +|:---------|:-----------| +| usage? | Instructions on how and when to use this resource type in a RAML spec +| uses? | You may import library locally here it contents is accessible only inside of this trait +| parameters? | Optional declaration of the parameters that the resource type employs. + +The following example illustrates the declaration of several resource types and traits. + +```yaml +#%RAML 1.0 +title: Example API +version: v1 +resourceTypes: + collection: + usage: This resourceType should be used for any collection of items + description: The collection of <> + get: + description: Get all <>, optionally filtered + post: + description: Create a new <> +traits: + secured: + usage: Apply this to any method that needs to be secured + description: Some requests require authentication. + headers: + access_token: + description: Access Token + example: 5757gh76 + required: true +``` + +The following example builds on the previous one, but the the resource types and traits are defined in external files that are included by using an !include tag. + +```yaml +#%RAML 1.0 +title: Example API +version: v1 +resourceTypes: + - collection: !include resourceTypes/collection.raml + - member: !include resourceTypes/member.raml +traits: + - secured: !include traits/secured.raml + - rateLimited: !include traits/rate-limited.raml +``` + +### Usage + +The OPTIONAL **usage** property of a resource type or trait provides instructions on how and when the resource type or trait should be used. Documentation generators MUST convey this property as characteristics of the resource and method, respectively. However, the resources and methods MUST NOT inherit the usage property: neither resources nor methods allow a property named usage. + +### Resource Type and Trait Parameters + +The declarations of resource types and traits MAY contain parameters, whose values MUST be specified when applying the resource type or trait, UNLESS the parameter corresponds to a reserved parameter name, in which case its value MUST be provided by the processing application. + +Parameters are indicated in resource type and trait definitions by double angle brackets (double chevrons) enclosing the parameter name; for example, <>. + +In resource type and trait declarations, there are two reserved parameter names: **resourcePath** and **resourcePathName**. + +| Parameter | Value | +|:---------|:-----------| +| resourcePath | The resource's full URI relative to the baseUri (if any) +| resourcePathName | The rightmost path fragment of the resource's relative URI, omitting any parametrizing brackets ("{" and "}") + +A processing application MUST set the value of <> to the concatenation of the inheriting resource's relative URI with all its parent resources' relative URIs, that is, to its URI relative to the baseUri (if any). For example, a resource /users nested in a resource /{groupId} nested in a root-level resource /groups, and applying a resource type or trait that uses the resourcePath parameter, would have the value of that parameter set to /groups/{groupId}/users. + +A processing application MUST set the value of <> to the part of the inheriting resource's relative URI following the rightmost slash ("/"), after omitting any parametrizing brackets ("{" and "}"). For example, a resource /jobs/{jobId} applying a resource type or trait that uses the resourcePathName parameter would have the value of that parameter set to jobId. + +Processing applications MUST also omit any ext parameter and its parametrizing brackets ("{" and "}") found in the resource's URI when setting resourcePath and resourcePathName. For example, a root-level resource /bom/{itemId}{ext} applying a resource type or trait that uses the resourcePathName and resourcePath parameters would have the value of those parameters set to /bom/{itemId} and itemId, respectively. + +In trait declarations, there is an additional reserved parameter named **methodName**. + +| Parameter | Value | +|:---------|:-----------| +| methodName | The name of the method + +The processing application MUST set the value of the methodName parameter to the inheriting method's name. + +Parameter values MAY further be transformed by applying one of the following functions. + +| Function | Definition | +|:---------|:-----------| +| !singularize | The !singularize function MUST act on the value of the parameter by a locale-specific singularization of its original value. The only locale supported by this version of RAML is United States English. +| !pluralize | The !pluralize function MUST act on the value of the parameter by a locale-specific pluralization of its original value. The only locale supported by this version of RAML is United States English. +| !uppercase | effect: `userId --> USERID` +| !lowercase | effect: `userId --> userid` +| !lowercamelcase | effect: `userId --> userId` +| !uppercamelcase | effect: `userId --> UserId` +| !lowerunderscorecase | effect: `userId --> user_id` +| !upperunderscorecase | effect: `userId --> USER_ID` +| !lowerhyphencase | `effect: userId --> user-id` +| !upperhyphencase | effect: userId --> USER-ID` + +To apply these functions, append them to the parameter name within the double angle brackets, separated from the parameter name with a pipe ("|") character and optional whitespace padding. Here is an example that uses both functions as well as reserved parameters: + +```yaml +#%RAML 1.0 +title: Example API +version: v1 +mediaType: application/json +types: + Users: !include types/users.raml + User: !include types/user.raml +resourceTypes: + - collection: + get: + responses: + 200: + body: + type: <> # e.g. Users + post: + responses: + 200: + body: + type: <> # e.g. User + - member: + get: + responses: + 200: + body: + type: <> # e.g. User +traits: + - secured: + description: Some requests require authentication + queryParameters: + <>: # e.g. get: + description: A <>-token pair is required # e.g. A get-token pair... + example: <>=h8duh3uhhu38 # e.g. get=h8duh3uhhu38 +``` + +Parameters may not be used within !include tags, that is, within the location of the file to be included. + +### Optional Properties + +When defining resource types and traits, it can be useful to capture patterns that manifest several levels below the inheriting resource or method, without mandating the creation of the intermediate levels. For example, a resource type declaration may describe a body parameter that would be used if the API defines a post method for that resource, but applying the resource type to a resource without a post method should not create the post method. + +To accommodate this need, a resource type or trait definition MAY append a question mark ("?") suffix to the name of any object-valued property that should not be applied if it doesn't already exist in the resource or method at the corresponding level. A property is considered object-valued if its value is of type object or of a type that has object at the base of its inheritance hierarchy. The question mark suffix indicates that the value of the property in the resource type or trait should be applied if the property name itself (without the question mark) is already defined (whether explicitly or implicitly) at the corresponding level in that resource or method. + +The following example shows a resource type called corpResource with an optional post? property that defines a required header called X-Chargeback. If the inheriting resource defines a post method, it will include the X-Chargeback header requirement. If the inheriting resource does not define a post method, one will not be defined for it by dint of inheriting from the corpResource resource type. + +```yaml +#%RAML 1.0 +title: Example of Optional Properties +resourceTypes: + - corpResource: + post?: + headers: + X-Chargeback: + required: true +/servers: + type: corpResource + get: + post: # will require the X-Chargeback header +/queues: + type: corpResource + get: + # will not have a post method defined +``` + +Note that a question mark can also appear as the last character of a RAML Type property name. If you wish to use this syntax within a Resource Type or Trait you should escape it with a backslash ( "\?"). Consider an example of body type defined inside trait by a properties set: + +```yaml +#%RAML 1.0 +title: Example of Optional Properties of Types Defined in Trait +traits: + - hasPayload: + body: + application/json: + properties: + name: + address\?: + location?: +/servers: + post: + is: [ hasPayload ] + # will have application/json body with 'name' required property, + # 'address' optional property, but without 'location' property +``` + +The POST:/servers method obtains an application/json body with with 'name' required property, 'address' optional property, but without 'location' property. + +It is important to note that this feature applies only to object-valued properties; the appending of the optional marker ("?") to a scalar- or array-valued property such as description or security schemes MUST be rejected by RAML parsers. + +### Applying Resource Types and Traits + +The OPTIONAL **type** property applies a resource type to a resource, so that the resource inherits the resource type's characteristics. The value of the **type** property is either a) a name of a resource type declared in the resourceTypes declaration, or b) an inline (anonymous) resource type declaration. + +The OPTIONAL **is** property applies any number of traits to a method, so that the method inherits the trait's or traits' characteristics. The value of the is attribute is an array of any number of elements, each of which is either a) a name of a trait declared in the traits declaration, or b) an inline (anonymous) trait declaration. + +A trait may also be applied to a resource by using the **is** key, which is equivalent to applying the trait to all methods for that resource, whether declared explicitly in the resource definition or inherited from a resource type. + +The following example illustrates the application of resource types and traits. + +```yaml +#%RAML 1.0 +title: Example API +version: v1 +resourceTypes: + collection: !include resourceTypes/collection.raml + member: !include resourceTypes/member.raml +traits: + secured: !include traits/secured.raml + paged: !include traits/paged.raml + rateLimited: !include traits/rate-limited.raml +/users: + type: collection + is: [ secured ] + get: + is: [ paged, rateLimited ] # this method is also secured + post: # this method is also secured +``` + +To pass parameter values to resource types and traits, use a map when declaring the resource type or trait to be used, as illustrated in the following example. + +```yaml +#%RAML 1.0 +title: Example API +version: v1 +resourceTypes: + searchableCollection: + get: + queryParameters: + <>: + description: Return <> that have their <> matching the given value + <>: + description: If no values match the value given for <>, use <> instead +traits: + secured: + queryParameters: + <>: + description: A valid <> is required + paged: + queryParameters: + numPages: + description: The number of pages to return, not to exceed <> +/books: + type: { searchableCollection: { queryParamName: title, fallbackParamName: digest_all_fields } } + get: + is: [ secured: { tokenName: access_token }, paged: { maxPages: 10 } ] +``` + +### Algorithm of Merging Traits With Methods + +Each RAML element has its branch of the RAML document. Informally, applying a trait to method may be described as putting traits branch under the methods branch. +Formally, it is a recursive procedure: +1. Those properties of method node which are undefined in trait node remain unchanged. +2. The method node receives all properties of trait node (excluding optional) which are undefined in method node. +3. As for properties defined in both method node and trait node (including optional): + * Scalar properties remain unchanged + * Collection properties are merged by value (see below) + * Values of object properties are subjected to the same procedure starting at step 1. + +In general case a method can have more than one trait each having a sufficient hierarchy. Applying all of them is equivalent to building a stack of branches: + +1. Top branch is the methods branch. +2. Other branches are traits branches. + * Branches of those traits which are farther from the method in hierarchical sense, lay deeper (a trait may occur on different hierarchy distances, and we consider the closest one). + * Those traits which lay on the same hierarchy distance from the method, can be ordered in a queue: + * For distance one it's just the methods trait list. + * Queue(d+1) is obtained from Queue(d) by concatenating trait lists of its elements and canceling all but the first occurence of each trait. + * Branches order is determined as follows: those traits, which have higher positions in the queue, also have their branches deeper in our stack. + +Finally, the resource can have its own traits, and it can be applied a chain of resource types (call them resourceType1, resourceType2, etc), each possibly having its own traits and defining the same method. The stack is constructed as follows: +1. Traits of method itself +2. Traits of resource owning the method +3. Traits of method owned by resourceType1 +4. Traits of resourceType1 +5. etc. + +Merging resource types with resources obeys similar rules. + +### Resource Types and Traits Effect on Collections + +All the collections or sequences which fall under effect of applying traits and resource types are merged. Consider an example of query parameter which has its enum values defined in both resource and trait: + +```yaml +#%RAML 1.0 +title: Example API +version: v1 +traits: + parameters: + queryParameters: + platform: + enum: + - win + - mac +/installer: + get: + queryParameters: + platform: #the actual enum is [ mac, unix, win ] + enum: + - mac + - unix +``` + +In this example the resulting enum value is `[ mac, unix, win ]`. + +Important case of collections is a trait, which can appear as "is" attribute value for method, resource, trait or resource type. Such lists may contain same traits which differ in parameter sets and, thus, can not be considered equal: + +```yaml +#%RAML 1.0 +title: Example API +version: v1 +resourceTypes: + apiResource: + get: + is: [ { secured : { tokenName: access_token } } ] +traits: + secured: + queryParameters: + <>: + description: A valid <> is required +/servers: + get: + is: [ { secured : { tokenName: token } } ] +``` + +In resolving such a collision priority is given to that trait occurrence which is closer to the target method (or resource). In the example above the `tokenName` parameter value for the `GET:/servers` method is `token`, and the trait list consists of single trait occurrence: `[ {secured:{ tokenName:token}} ]`. + +## Security Schemes + +Most REST APIs have one or more mechanisms to secure data access, identify requests, and determine access level and data visibility. + +This section describes how an API designer MAY include security scheme definitions in RAML API definitions. This section also outlines the support documentation that the client and server implementation generators SHOULD include. + +### Security Scheme Types + +RAML supports the following built-in security scheme types: + +|Type |Description| +|:----------|:----------| +|OAuth 1.0 | The API's authentication requires using OAuth 1.0 as described in [RFC5849](https://tools.ietf.org/html/rfc5849) +|OAuth 2.0 | The API's authentication requires using OAuth 2.0 as described in [RFC6749](https://tools.ietf.org/html/rfc6749) +|Basic Authentication| The API's authentication relies on using Basic Access Authentication as described in [RFC2617](https://tools.ietf.org/html/rfc2617) +|Digest Authentication| The API's authentication relies on using Digest Access Authentication as described in [RFC2617](https://tools.ietf.org/html/rfc2617) +|Pass Through| Headers or Query Parameters are passed through to the API based on a defined mapping. +|x-{other}| The API's authentication relies on another authentication method. + +A processing application's developers MAY provide support for these mechanisms. If a mechanism is supported, it MUST conform to the specified standard. + +Additionally, any security scheme definition may be augmented with a describedBy property, which allows the designer to document the API's security scheme. + +### Security Scheme Declaration + +Security scheme is declared as follows: + +|Property |Description| +|:----------|:----------| +| type | The security schemes property MUST be used to specify an API's security mechanisms, including the required settings and the authentication methods that the API supports. one authentication method is allowed if the API supports them. The value MUST be one of the following: OAuth 1.0, OAuth 2.0, Basic Authentication, Digest Authentication, Pass Through, x-<other> +| description? | The description MAY be used to describe a security scheme. +| describedBy? | A description of the request components related to Security that are determined by the scheme: the headers, query parameters or responses. As a best practice, even for standard security schemes, API designers SHOULD describe these properties of security schemes. Including the security scheme description completes an API documentation. See explanation about [describedBy](#describedBy) for more information. +| settings? | The settings attribute MAY be used to provide security scheme-specific information. The required attributes vary depending on the type of security scheme is being declared. It describes the minimum set of properties which any processing application MUST provide and validate if it chooses to implement the security scheme. Processing applications MAY choose to recognize other properties for things such as token lifetime, preferred cryptographic algorithms, and more. See explanation about [seetings](#settings) for more information. + +An optional **securitySchemes** property is defined for RAML document root. +As value it has an object whose properties map security scheme names to security scheme declarations. +Each authentication pattern supported by the API must be expressed as component of **securitySchemes** property value. + +In this example, the Dropbox API supports authentication via OAuth 2.0 and OAuth 1.0: +```yaml +#%RAML 1.0 +title: Dropbox API +version: 1 +baseUri: https://api.dropbox.com/{version} +securitySchemes: + - oauth_2_0: + description: | + Dropbox supports OAuth 2.0 for authenticating all API requests. + type: OAuth 2.0 + describedBy: + headers: + Authorization: + description: | + Used to send a valid OAuth 2 access token. Do not use + with the "access_token" query string parameter. + type: string + queryParameters: + access_token: + description: | + Used to send a valid OAuth 2 access token. Do not use together with + the "Authorization" header + type: string + responses: + 401: + description: | + Bad or expired token. This can happen if the user or Dropbox + revoked or expired an access token. To fix, you should re- + authenticate the user. + 403: + description: | + Bad OAuth request (wrong consumer key, bad nonce, expired + timestamp...). Unfortunately, re-authenticating the user won't help here. + settings: + authorizationUri: https://www.dropbox.com/1/oauth2/authorize + accessTokenUri: https://api.dropbox.com/1/oauth2/token + authorizationGrants: [ authorization_code, refresh_token ] + - oauth_1_0: + description: | + OAuth 1.0 continues to be supported for all API requests, but OAuth 2.0 is now preferred. + type: OAuth 1.0 + settings: + requestTokenUri: https://api.dropbox.com/1/oauth/request_token + authorizationUri: https://www.dropbox.com/1/oauth/authorize + tokenCredentialsUri: https://api.dropbox.com/1/oauth/access_token +``` + +#### describedBy + +The value of the **describedBy** property is defined as follows: + +|Property |Description| +|:----------|:----------| +| headers? | Optional array of headers, documenting the possible headers that could be accepted. See section [Headers](#headers) for more information. +| queryParameters? | Query parameters, used by the schema in order to authorize the request. Mutually exclusive with queryString. See section [Query Strings and Query Parameters](#query-strings-and-query-parameters) for more information. +| queryString? | Specifies the query string, used by the schema in order to authorize the request. Mutually exclusive with queryParameters. See section [Query Strings and Query Parameters](#query-strings-and-query-parameters) for more information. +| responses? | Optional array of responses, describing the possible responses that could be sent. See section [Responses](#responses) for more information. +| displayName? | An alternate, human-friendly name for the security scheme part +| description? | A longer, human-friendly description of the security scheme part +| (<annotationName>)? | Annotations to be applied to this security scheme part. Annotations are any property whose key begins with "(" and ends with ")" and whose name (the part between the beginning and ending parentheses) is a declared annotation name. See section [Annotations](#annotations) for more information. + +#### Settings + +The settings attribute MAY be used to provide security scheme specific information. The required attributes vary depending on the type of security scheme is being declared. + +It describes the minimum set of properties which any processing application MUST provide and validate if it chooses to implement the security scheme. Processing applications MAY choose to recognize other properties for things such as token lifetime, preferred cryptographic algorithms, and more. + +##### OAuth 1.0 + +Security schemes of this type have specific settings object: + +|Property |Description | +|:--------|:------------| +|requestTokenUri| The URI of the *Temporary Credential Request endpoint* as defined in [RFC5849 Section 2.1](https://tools.ietf.org/html/rfc5849#section-2.1) +|authorizationUri| The URI of the *Resource Owner Authorization endpoint* as defined in [RFC5849 Section 2.2](https://tools.ietf.org/html/rfc5849#section-2.2) +|tokenCredentialsUri| The URI of the *Token Request endpoint* as defined in [RFC5849 Section 2.3](https://tools.ietf.org/html/rfc5849#section-2.3) + +OAuth 1.0 authentication follows the standard described in [RFC5849](https://tools.ietf.org/html/rfc5849). The following is an example: + +```yaml +#%RAML 1.0 +title: Dropbox API +version: 1 +baseUri: https://api.dropbox.com/{version} +securitySchemes: + - oauth_1_0: + description: | + OAuth 1.0 continues to be supported for all API requests, but OAuth 2.0 is now preferred. + type: OAuth 1.0 + settings: + requestTokenUri: https://api.dropbox.com/1/oauth/request_token + authorizationUri: https://www.dropbox.com/1/oauth/authorize + tokenCredentialsUri: https://api.dropbox.com/1/oauth/access_token +``` + +##### OAuth 2.0 + +Security schemes of this type has specific settings object: + +|Property |Description | +|:--------|:------------| +|authorizationUri| The URI of the *Authorization Endpoint* as defined in [RFC6749 Section 3.1](https://tools.ietf.org/html/rfc6749#section-3.1) +|accessTokenUri| The URI of the *Token Endpoint* as defined in [RFC6749 Section 3.2](https://tools.ietf.org/html/rfc6749#section-3.2) +|authorizationGrants| A list of the Authorization grants supported by the API As defined in RFC6749 Sections [4.1](https://tools.ietf.org/html/rfc6749#section-4.1), [4.2](https://tools.ietf.org/html/rfc6749#section-4.2), [4.3](https://tools.ietf.org/html/rfc6749#section-4.3) and [4.4](https://tools.ietf.org/html/rfc6749#section-4.4), can be any of: code, token, owner or credentials. +|scopes| A list of scopes supported by the API as defined in [RFC6749 Section 3.3](https://tools.ietf.org/html/rfc6749#section-3.3) + +OAuth 2.0 authentication follows the standard described in [RFC6749](https://tools.ietf.org/html/rfc6749). The following is an example: + +```yaml +#%RAML 1.0 +title: Dropbox API +version: 1 +baseUri: https://api.dropbox.com/{version} +securitySchemes: + - oauth_2_0: + description: | + Dropbox supports OAuth 2.0 for authenticating all API requests. + type: OAuth 2.0 + describedBy: + headers: + Authorization: + description: | + Used to send a valid OAuth 2 access token. Do not use + with the "access_token" query string parameter. + type: string + queryParameters: + access_token: + description: | + Used to send a valid OAuth 2 access token. Do not use together with + the "Authorization" header + type: string + responses: + 401: + description: | + Bad or expired token. This can happen if the user or Dropbox + revoked or expired an access token. To fix, you should re- + authenticate the user. + 403: + description: | + Bad OAuth request (wrong consumer key, bad nonce, expired + timestamp...). Unfortunately, re-authenticating the user won't help here. + settings: + authorizationUri: https://www.dropbox.com/1/oauth2/authorize + accessTokenUri: https://api.dropbox.com/1/oauth2/token + authorizationGrants: [ authorization_code, refresh_token ] +``` + +##### Basic Authentication + +Note: Basic security does not require any further specification of settings in the API Definition. + +```yaml +#%RAML 1.0 +title: Dropbox API +version: 1 +baseUri: https://api.dropbox.com/{version} +securitySchemes: + - basic: + description: | + This API supports Basic Authentication. + type: Basic Authentication +``` + +##### Digest Authentication + +Note: Digest security does not require any further specification of settings in the API Definition. + +```yaml +#%RAML 1.0 +title: Dropbox API +version: 1 +baseUri: https://api.dropbox.com/{version} +securitySchemes: + - digest: + description: | + This API supports DigestSecurityScheme Authentication. + type: Digest Authentication +``` + +##### Pass Through + +Pass Through authentication does not have any specific settings defined and the implementation is known to RAML. For every header or queryParameter defined in describedBy, the value is required and passed along with the request without modification. The following is an example: + +```yaml +#%RAML 1.0 +title: Dropbox API +version: 1 +baseUri: https://api.dropbox.com/{version} +securitySchemes: + - passthrough: + description: | + This API supports Pass Through Authentication. + type: Pass Through + describedBy: + queryParameters: + query: + type: string + headers: + api_key: + type: string +``` + +##### x-<other> + +x-<other> authentication methods do not have any specific settings defined, as their implementation is unknown as a standard for RAML. These security schemes may only include a description and a describedBy section, to allow documentation of the intended use of the security scheme. The following is an example: + +```yaml +#%RAML 1.0 +title: Custom API +version: 1 +baseUri: https://api.custom.com/{version} +securitySchemes: + - custom_scheme: + description: | + A custom security scheme for authenticating requests. + type: x-custom + describedBy: + headers: + SpecialToken: + description: | + Used to send a custom token. + type: string + responses: + 401: + description: | + Bad token. + 403: +``` + +#### Applying Security Schemes + +The **securedBy** attribute of RAML document root may be used to apply security schemes to every method of API. This specifies that all methods in the API (unless they have their own securedBy attribute) can be authenticated by any mentioned security scheme. + +Applying a security scheme to a method overrides whichever security scheme has been applied to the API as whole. +To indicate that the method is protected using a specific security scheme, the method MUST be defined by using the **securedBy** attribute. + +The value assigned to the securedBy attribute MUST be a list of any of the security schemes previously defined in the **securitySchemes** property of RAML document root. + +```yaml +#%RAML 1.0 +title: Dropbox API +version: 1 +baseUri: https://api.dropbox.com/{version} +securedBy: [oauth_2_0] +securitySchemes: + - oauth_2_0: !include securitySchemes/oauth_2_0.raml + - oauth_1_0: !include securitySchemes/oauth_1_0.raml +/users: + get: + securedBy: [oauth_2_0, oauth_1_0] +``` + +To indicate that the method may be called without applying any security scheme, the method may be provided with securedBy attribute containing null as array component. + +```yaml +#%RAML 1.0 +title: GitHub API +version: v3 +baseUri: https://api.github.com +securitySchemes: + - oauth_2_0: !include securitySchemes/oauth_2_0.raml +/users/{userid}/gists: + get: + securedBy: [null, oauth_2_0] +``` + +A resource can also be applied a list of security schemes using the **securedBy** attribute. This specifies that all methods of this particular resource (unless they have their own securedBy attribute) can be authenticated by any mentioned security scheme. Value of resources attribute overrides that of the root attribute. + +Applying a security scheme to a method overrides security schemes applied to the API and resources having the method as sibling. + +If the processing application supports custom properties, custom parameters can be provided to the security scheme at the moment of inclusion in a method. + +In the following example, the parameter **scopes** is being assigned: + +```yaml +#%RAML 1.0 +title: GitHub API +version: v3 +baseUri: https://api.github.com +securitySchemes: + - oauth_2_0: !include securitySchemes/oauth_2_0.raml +/users/{userid}/gists: + get: + securedBy: [null, oauth_2_0: { scopes: [ ADMINISTRATOR ] } ] +``` + +The list of parameters that must and may be provided to the security scheme is specified by the security scheme type. + +## Annotations + +Annotations provide a mechanism to extend the API specification with metadata beyond the metadata already defined in this RAML 1.0 specification. Annotations can also be regarded as a mechanism to add properties to the built-in RAML properties in certain locations within the RAML specification. Processors MAY support certain annotations to add additional specificity to the API description, enable tooling such as testing, support API repositories and API discovery, and so on. Processors MAY ignore any and all annotations. + +Annotations used in an API specification MUST be declared in a root-level annotationTypes property. Annotations can have values, which are defined and constrained in annotation type declarations. Processors can then rely on the declarations to ensure annotation values are as expected. + +The following is an example of various annotation type declarations and the application of the annotations to an API definition. + +```yaml +#%RAML 1.0 +title: Illustrating annotations +mediaType: application/json +annotationTypes: + experimental: + feedbackRequested: + testHarness: + type: string # This line may be omitted as it's the default type + badge: # This annotation type, too, allows string values + assertion: + allowMultiple: true + clearanceLevel: + properties: + level: + enum: [ low, medium, high ] + required: true + signature: + pattern: "\\d{3}-\\w{12}" + required: true +/groups: + (experimental): + (feedbackRequested): +/users: + (testHarness): usersTest + (badge): tested.gif + (clearanceLevel): + level: high + signature: 230-ghtwvfrs1itr + get: + (experimental): + (feedbackRequested): + responses: + 200: + (assertion): Condition 1 + (assertion): Condition 2 +``` + +Annotations applied to a data type are not inherited when that data type is inherited. However, processors SHOULD make the information about the annotations in the data type hierarchy available. Annotations applied to, or applied within, a resource type or trait are also applied to the resource type or resource or method that inherits it. In particular, if a trait is applied to a resource type or resource, all annotations on or within that trait are applied implicitly to all methods of that resource. If the inheriting resource type or resource or method directly (explicitly) apply an annotation of a given type, then this annotation overrides all applications of that annotation type which would otherwise have been inherited and implicitly applied. In particular, if a trait is applied to a resource type or resource, and the resource type or resource apply an annotation of some type, then any and all applications of annotations of that type to that trait are overridden. + +### Declaring Annotation Types + +Annotation types are declared using the OPTIONAL root-level **annotationTypes** property. The value of the annotationsType property is an object whose keys define annotation type names, also referred to as annotations, and whose values are objects called annotation type declarations. An annotation type declaration has the same syntax as a data type declaration, and its facets have the same syntax as the corresponding ones for data types, but with the addition of 2 facets: allowMultiple and allowedTargets. Just as a data type declaration constrains the value of a URI parameter, query parameter, header, or body of that type, so an annotation type declaration constrains the value of an annotation of that type. The allowMultiple facet determines whether the annotation may be applied multiple times at the same location, while the allowedTargets facet restricts at which kinds of locations the annotation may be applied. Annotation types, like data types, may extend other data types, but annotation types may not themselves be extended nor used anywhere data types may be used. + +|Property |Description | +|:--------|:------------| +| displayName? | The displayName attribute specifies the $self's display name. It is a friendly name used only for display or documentation purposes. If displayName is not specified, it defaults to the element's key (the name of the property itself). +| description? | The description attribute describes the intended use or meaning of an annotation. This value MAY be formatted using markdown. +| (<annotationName>)? | Annotations to be applied to this annotation type. Annotations are any property whose key begins with “(“ and ends with “)” and whose name (the part between the beginning and ending parentheses) is a declared annotation name. See section [Annotations](#annotations) for more information. +| allowMultiple? | Whether multiple instances of annotations of this type may be applied simultaneously at the same location. +| allowedTargets? | Restrictions on where annotations of this type can be applied. If this property is specified, annotations of this type may only be applied on a property corresponding to one of the target names specified as the value of this property. Value MUST be one or more of the options described in table [Annotation Target Location](#annotation-target-location). + +If an annotation type declaration specifies neither a type facet nor a properties facet, then it defaults to a type of string. + +All annotations used in an API specification MUST be declared in its annotationTypes property. Any value of an annotation MUST be valid according to its annotation type. + +If the allowedTargets property is not present, then the annotation may be applied in any of the target locations listed in the Target Locations table below. If the allowedTargets property is present, it restricts where the annotation may be applied, as described in the section below. + + +### Applying Annotations + +For an annotation to be applied in an API specification, the annotation MUST be declared in an annotation type. + +A declared annotation may be applied to an object in the specification by adding a property on that object whose key is the name of the annotation type enclosed in parentheses, and whose value is called an annotation value and MUST be valid according to the corresponding annotation type. + +The example below, a small subset of the previous example, shows an explicit declaration and use of a testHarness annotation whose value should be a string. + +```yaml +#%RAML 1.0 +title: Testing annotations +mediaType: application/json +annotationTypes: + testHarness: + type: string +/users: + (testHarness): usersTest +``` + +The following is semantically equivalent but relies on the implicit default declaration of the value type when there is no explicit type declaration. + +```yaml +#%RAML 1.0 +title: Testing annotations +mediaType: application/json +annotationTypes: + testHarness: +/users: + (testHarness): usersTest +``` + +The location within an API specification where annotations may be applied MUST be one of the target locations in the following Target Locations table. The targets are the locations themselves, not sub-properties within the locations; for example, the Method target refers to the method property and not to the method's display name, description, etc. + + + +|Target | Description | +|:--------|:------------| +| API | The root of a RAML document +| DocumentationItem | An item in the collection of items that is the value of the root-level documentation property. +| Resource | A resource (relative URI) property, root-level or nested +| Method | A method property +| Response | A property of the responses property, whose key is an HTTP status code +| RequestBody | The body property of a method +| ResponseBody | The body property of a response +| TypeDeclaration | A data type declaration (inline or in a global types collection), header declaration, query parameter declaration, or URI parameter declaration, or property within any of these declarations, where the type property may be used. +| NamedExample | A property of the examples property, whose key is a name of an example and whose value describes the example. +| ResourceType | A resource type property +| Trait | A trait property +| SecurityScheme | A security scheme declaration +| SecuritySchemeSettings | The settings property of a security scheme declaration +| AnnotationTypeDeclaration | A property of the annotationTypes property, whose key is a name of an annotation type and whose value describes the annotation. +| Library | The root of a library declaration. +| Overlay | The root of an overlay declaration. +| Extension | The root of an extension declaration. + +The following example illustrates applying some restrictions on the allowed targets of annotations. + +```yaml +#%RAML 1.0 +title: Illustrating allowed targets +mediaType: application/json +annotationTypes: + meta-resource-method: + allowedTargets: [ Resource, Method ] + meta-data: + allowedTargets: TypeDeclaration +types: + User: + type: object + (meta-data): on an object; on a data type declaration + properties: + name: + type: string + (meta-data): on a string property +/users: + (meta-resource-method): on a resource + get: + (meta-resource-method): on a method + responses: + 200: + body: + type: User[] + (meta-data): on a body +``` + +## Modularization + +RAML provides several mechanisms to help modularize your API specification and specifications ecosystem: +* Includes +* Libraries +* Overlays +* Extensions + +### Includes + +RAML processors MUST support the OPTIONAL **!include** tag, which specifies the inclusion of external files into the API specification. As it is a YAML tag, it starts with an exclamation point ("!"). The location in an API specification where an !include tag may be used MUST be the value of a property, so the result of including the file specified by the !include tag is the value of that property. + +In the following example, the set of types to be used elsewhere in the RAML specification is retrieved from a file called myTypes.raml and used as the value of the types property in the RAML specification. + +```yaml +#%RAML 1.0 +title: My API with Types +types: !include myTypes.raml +``` + +The !include tag accepts a single argument, the location of the content to be included, that MUST be specified explicitly. Its value MUST be one of the following: + +|Argument | Description | Examples | +|:--------|:------------|:---------| +| absolute path | A path that begins with a single slash ("/") and is to be interpreted relative to the root RAML file's location. | /traits/pageable.raml +| relative path | A path that does not begin with a single slash ("/") nor is a URL, and is to be interpreted relative to the including file's location. | description.md
    ../traits/pageable.raml +| URL | An absolute URL | http://dev.domain.com/api/patterns/traits.raml + +To simplify API definition, and because the included file's parsing context is not shared between the included file and its parent, an included file SHALL NOT use a YAML reference to an anchor in a separate file. Likewise, a reference made from a parent file SHALL NOT reference an anchor defined in an included file. + +The argument of the !include tag must be static: namely, it MUST NOT contain any resource type parameters or trait parameters. + +#### Typed Fragments + +A file to be included MAY begin with a RAML fragment identifier line, which consists of the text _#%RAML_ followed by a single space followed by the text 1.0, followed by a single space followed by one of the following fragment identifiers: + +|Fragment | Description | +|:--------|:------------| +| DocumentationItem | An item in the collection of items that is the value of the root-level documentation property; see the section on [User Documentation](#user-documentation). +| DataType | A data type declaration, where the type property may be used; see the section on [Types](#types) +| NamedExample | A property of the examples property, whose key is a name of an example and whose value describes the example; see the section on [Examples](#examples) +| ResourceType | A single resource type declaration; see the section on [Resource Types and Traits](#resource-types-and-traits) +| Trait | A single trait declaration; see the section on [Resource Types and Traits](#resource-types-and-traits) +| AnnotationTypeDeclaration | A single annotation type declaration; see the section on [Annotations](#annotations) +| Library | A RAML library; see the section on [Libraries](#libraries). +| Overlay | An overlay file; see the section on [Overlays](#overlays). +| Extension | An extension file; see the section on [Extensions](#extensions). + +If a file begins with a RAML fragment identifier line, and the fragment identifier is neither Library nor Overlay nor Extension, the contents of the file after removal of the RAML fragment identifier line MUST be valid structurally according to the corresponding section of this RAML specification. For example, a RAML file beginning with `#%RAML 1.0 Trait` must have the structure of a RAML trait declaration as defined in the [specification for traits](#resource-types-and-traits), such that including the file in a location where a trait declaration is called for results in a valid RAML file. + +The following example shows a RAML fragment file that defines a resource type, and a file that includes this fragment file. + + +```yaml +#%RAML 1.0 ResourceType + +#This file is located at resourceTypes/collection.raml + +description: A collection resource +usage: Use this to describe resource that list items +get: + description: Retrieve all items +post: + description: Add an item + responses: + 201: + headers: + Location: +``` + +```yaml +#%RAML 1.0 +title: Products API +resourceTypes: + collection: !include resourceTypes/collection.raml +/products: + type: collection + description: All products + +``` + +The resulting API definition is equivalent to the following single document. + +```yaml +#%RAML 1.0 +title: Products API +resourceTypes: + collection: + description: A collection resource + usage: Use this to describe resource that list items + get: + description: Retrieve all items + post: + description: Add an item + responses: + 201: + headers: + Location: +/products: + type: collection + description: All products +``` + +#### Resolving Includes + +When RAML or YAML files are included, RAML parsers MUST not only read the content, but parse it and add the content to the declaring structure as if the content were declared inline. Specifically, if the included file has one of the following media types: + +* application/raml+yaml +* text/yaml +* text/x-yaml +* application/yaml +* application/x-yaml + +or a .raml or .yml or .yaml extension, RAML parsers MUST parse the content the file as RAML content and append the parsed structures to the RAML document's node. Otherwise, the contents of the file will be included as a scalar. + +To simplify RAML definitions, and because the included files parsing context is not shared between the included file and its parent, an included file SHALL NOT use a YAML reference to an anchor in a separate file. Likewise, a reference made from a parent file SHALL NOT reference a structure anchor defined in an included file. + +In the example below, the API root document includes two files from the patterns folder, one containing resource type declarations and the other containing trait declarations. + +```yaml +#%RAML 1.0 +title: Example API +version: v1 +resourceTypes: !include patterns/resourceTypes.raml +traits: !include patterns/traits.raml +``` + +```yaml +#%RAML 1.0 +# This file is located at patterns/resourceTypes.raml + +collection: + get: + is: paged + post: +member: + get: + patch: + delete: +``` + +```yaml +#%RAML 1.0 +# This file is located at patterns/traits.raml + +chargeable: + headers: + dept_code: +paged: + queryParameters: + start: + type: number +``` + +The resulting API definition is equivalent to the following single document. + +```yaml +#%RAML 1.0 +title: Example API +version: v1 +resourceTypes: + collection: + get: + is: paged + post: + member: + get: + patch: + delete: +traits: + chargeable: + headers: + dept_code: + paged: + queryParameters: + start: + type: number +``` + +#### References to inner elements of external files + +RAML 1.0 supports referring to inner elements of included schemas by using URL fragments. + + +```yaml +schema: !include elements.xsd#Foo +``` + +```yaml +/id: !include myContent.raml#feature +``` + +Dereferencing to a fragment of JSON schemas is performed according to default JSON Schema dereferencing rules (see chapter 7 in http://json-schema.org/latest/json-schema-core.html) + +Dereferencing to a fragment of XSD schema is described in *3.15.2.2 References to Schema Components*, [XML Schema Part 1: Structures Second Edition](http://www.w3.org/TR/xmlschema-1/). However there is a special shortcut: If you are referring to a named type within XSD schema you may simplify fragment definition to its name. + +Meaning of references to inner elements: referencing to inner element of schema is equivalent to referencing to the schema with a top level element with structural restrictions same as restrictions on the referenced element of schema. At this version of RAML specification it is allowed to refer on elements of schemas in the following cases: + +* referencing to an element of JSON schema is valid in any context, but they do not define name of top level XML element when serializing to XML payload +* referencing to an element of XSD schema is valid in any context +* references to XSD complex types are valid to determine inner structure of payload but they do not define name of top level XML element when serializing to XML payload +* any other kinds of references does not have well defined meaning + +### Libraries + +RAML libraries are used to combine any collection of data type declarations, resource type declarations, trait declarations, and security scheme declarations into modular, externalized, reusable groups. While libraries are meant to allow definition of common declarations in external documents which are then included where needed, they may also be defined inline. + +A library is an object whose allowed properties are enumerated in the following table. Each is optional. + +|Property | Description | +|:--------|:------------| +| types?
    chemas?
    resourceTypes?
    traits?
    securitySchemes?
    annotationTypes?
    (<annotationName>)?
    uses? | The definition of each property is the same as that of the corresponding property in the root of a RAML document. Annotation properties are allowed as in any other RAML document. + +The following example shows a simple library as a standalone, reusable RAML fragment document. + +```yaml +#%RAML 1.0 Library +usage: | + Use to define some basic file-related constructs. +types: + File: + properties: + name: + length: + type: integer +traits: + drm: + headers: + drm-key: +resourceTypes: + file: + get: + is: drm + put: + is: drm +``` + +#### Applying Libraries + +Any number of libraries may be applied by using the OPTIONAL **uses** property. The value of the uses property is an object whose property names are treated as library names and whose property values are libraries, usually included from an external RAML library fragment document. + +When a library is applied, the data types, resource types, traits, security schemes, and annotation types which it declared are made available in the document in which it was applied, but are referenced via names formed by concatenating the library name followed by a period (".") followed by the name of the data type, resource type, trait, security scheme, or annotation type. In this way the library name defines a namespace for the library's objects within the context in which the library was applied. Libraries may be applied in RAML fragment documents such as trait and resource type fragment documents to make such documents more standalone by including their dependencies. + +The following examples demonstrate the use of a library in a second library, and the use of that second library in a resource type fragment as well as in RAML API definition. + +```yaml +#%RAML 1.0 Library +# This file is located at libraries/file-type.raml +types: + File: + properties: + name: + length: + type: integer +``` + +```yaml +#%RAML 1.0 Library +# This file is located at libraries/files.raml +usage: | + Use to define some basic file-related constructs. +uses: + file-type: !include libraries/file-type.raml +traits: + drm: + headers: + drm-key: +resourceTypes: + file: + get: + is: drm + put: + is: drm +``` + +```yaml +#%RAML 1.0 ResourceType +# This file is located at files-resource.raml +uses: + files: !include libraries/files.raml +get: + is: files.drm + responses: + 200: + body: + application/json: + type: files.file-type.File +``` + +```yaml +#%RAML 1.0 +title: Files API +uses: + files: !include libraries/files.raml +resourceTypes: + file: !include files-resource.raml +/files: + type: file +``` + +### Overlays and Extensions + +API definitions may need to be extended in a variety of ways for different needs. Annotations allow for adding metadata beyond that which is standardized in this RAML specification. Another set of needs is satisfied by overlaying standard or non-standard metadata on top of an existing API definition without changing its behavior, for example to specify implementation details or provide a translation of human-oriented documentation into different languages. Yet another set of needs requires extending an API definition by adding to its behavior or overriding certain aspects. RAML provides two mechanisms for doing so: overlays and extensions. + +Overlays and extensions are RAML documents that add or override properties of a RAML API definition. The first line of an overlay or extension document MUST begin with the text _#%RAML 1.0 Overlay_ or _#%RAML 1.0 Extension_, respectively, followed by nothing but the end of the line. An overlay or extension document MUST contain a root-level masterRef property whose value MUST be the location of a valid RAML API definition, or another overlay or extension; the location is specified equivalently to the location specified in the value of an !include tag (as an absolute or relative path or as a URL). The document specified in the masterRef property is called the master RAML document. + +The remainder of an overlay or extension document follows the same rules as a RAML API definition, but with certain restrictions in case of an overlay, as discussed in section about [Overlays](#overlays). + +To apply an overlay or extension, RAML processors MUST apply the merging algorithm described in the Merging Rules section below to the master RAML document and the extension or overlay, thereby producing a modified API definition; in the case of applying an overlay, the modified API definition is then validated against the master RAML document to adhere to the restrictions on overlays. + +To apply any combination of overlays and/or extensions, all of them must share the same master RAML document; the first is applied to the master RAML document as before, producing a modified API definition, and validating the result in the case of an overlay; then the second overlay or extension is applied to that modified API definition as if the latter were the master RAML document, and again validating the result in the case of an overlay; and so on until the last overlay or extension. All !include tags are resolved before any application of the merging algorithm, the validation of restrictions on overlays occurs after each overlay is applied, and all inheritances (of types, resource types, traits, and annotation types) are applied at the end of the application of all overlays and extensions. + +#### Overlays + +An overlay adds or overrides properties of a RAML API definition while preserving its behavioral, functional aspects. Certain properties of a RAML API definition specify the behavior of an API: its resources, methods, parameters, bodies, responses, etc. These may not be changed by applying an overlay. In contrast, other properties such as descriptions or annotations address concerns beyond the functional interface, such as the human-oriented descriptive documentation in some language, or implementation or verification information for use in automated tools. These may be changed by applying an overlay. + +Overlays are particularly important for separating interface from implementation, and for enabling separate lifecycles for the behavioral aspects of the API that need to be controlled more tightly as a contract between the API provider and its consumers, versus the human- or implementation-oriented aspects that can evolve at different paces. For example, adding hooks for testing and monitoring tools, appending metadata relevant to a registry of APIs, or or providing updated or translated human documentation can be achieved without changing any aspects of the behavioral aspects of the API, which may be controlled through a more rigorous version and change management process. + +While it is difficult to draw a definitive line between the two, for example because some semantics of the API is often captured only in human documentation, RAML does define the specific behavior-invariance restrictions on overlay files which processors MUST follow. Processors may then choose to offer the master API definition as well as its modifications after applying one or more overlays, so the consumer may benefit from all the information available; for example, if overlay files are provided as a means of localizing textual descriptions of resources, methods, and data, the consumer of generated documentation may be offered a choice of which localized overlays to apply. + +The behavior-invariance restrictions of an overlay are defined as follows: after applying the merging algorithm described in the Merging Rules section, and before any inheritances (of types, resource types, traits, and annotation types) are applied, the tree of nodes in the merged document is compared with the tree of nodes in the master RAML document after resolving all !include tags. Any differences MUST only be in properties listed in the following table. + +|Property | Allowed differences | +|:--------|:------------| +| title
    description
    documentation
    displayName
    usage
    example | The merged tree may include new properties of this type, or properties with different values than those in the master tree. +| types | In addition to allowed differences described elsewhere in this table, the merged tree may also include new data types. +| annotationTypes | The merged tree may include new annotation types, or new values for existing annotation types, as long as all annotations in the merged API definition validate against the annotation types in the merged tree. +| any annotation property | The merged tree may include new annotations of annotation types declared in the merged tree, or annotations with different values than those in the master tree. +| examples | The merged tree may contain new named examples, or named examples with different values than those in the master tree. +| documentation | The merged tree may contain new items in the array that is the value of the documentation root-level property. To change or remove existing items, the documentation property itself may be overridden in the overlay. + +The following example illustrates a (very) simple RAML definition of a library books API, along with an overlay file that provides a Spanish translation and an overlay file that provides metadata for an API monitoring service. + +```yaml +#%RAML 1.0 +# This file is located at librarybooks.raml +title: Book Library API +documentation: + - title: Introduction + content: Automated access to books + - title: Licensing + content: Please respect copyrights on our books. +/books: + description: The collection of library books + get: +``` + +```yaml +#%RAML 1.0 Overlay +usage: Spanish localization +masterRef: librarybooks.raml +documentation: + - title: Introducción + content: El acceso automatizado a los libros + - title: Licencias + content: Por favor respeta los derechos de autor de los libros +/books: + description: La colección de libros de la biblioteca +``` + +```yaml +#%RAML 1.0 Overlay +usage: Hints for monitoring the library books API +masterRef: librarybooks.raml +annotationTypes: + monitor: + parameters: + frequency: + properties: + interval: integer + unitOfMeasure: + enum: [ seconds, minutes, hours ] + script: +/books: + get: + (monitor): + frequency: + interval: 5 + unitOfMeasure: minutes + script: randomBooksFetch +``` + +#### Extensions + +An extension allows extending a RAML API definition by adding to, or modifying, its behavioral (functional) aspects as well as its non-behavioral aspects. This can be useful in separating a core, broadly-available API from layers of functionality available to more restricted audiences, for creating variants of an API for somewhat different purposes, or for specifying instance-specific properties of an API such as its service endpoint (URL) without altering its pure interface definition document. + +The following examples build on the examples in the overlays section above, by adding an extension available to admins for adding items (books) to a collection, adding an overlay to provide a translation of the added functionality, and adding an extension that locates a particular service endpoint of the API. + +```yaml +#%RAML 1.0 Extension +usage: Add administrative functionality +masterRef: librarybooks.raml +/books: + post: + description: Add a new book to the collection +``` + +```yaml +#%RAML 1.0 Overlay +usage: Spanish localization for admin functionality +masterRef: librarybooks.raml +/books: + post: + description: A?adir un nuevo libro para la colecci?n +``` + +```yaml +#%RAML 1.0 Extension +usage: The location of the public instance of the Piedmont library API +masterRef: librarybooks.raml +baseUri: http://api.piedmont-library.com +``` + +#### Merging Rules + +The algorithm of how exactly an overlay/extension structure is applied to the master is described in this section. + +##### Terminology + +###### Object & Property + +_Object_ is a MAP or a SEQUENCE containing MAPPINGS in terms of YAML. + +_Property_ is a MAPPING in terms of YAML, the pair of key and its value. + +In the following example, "properties" highlighted in yellow is a _Property_ key, and the corresponding _Object_ value is highlighted in green. + +
    +properties:
+  statusCode: 200
+    responseParameters:
+      type: object
+      description: "some description"
+
    + +In the same example, there is also a "responseParameters" _Property_ key and its _Object_ value colored in green: + +
    +properties:
+  statusCode: 200
+    responseParameters:
+      type: object
+      description: "some description"
+
    + +And while "statusCode", "type" and "description" colored yellow are also properties, their values are not _Objects_: + +
    +properties:
+   statusCode: 200
+   responseParameters:
+       type: object
+       description: "some description"
+
    + +In the following sample "FilteredByPrice" and "Paged" are yellow-colored _Properties_ with _Object_ values colored in green. + +
    +traits:
+ - FilterableByPrice:
+     queryParameters:
+       priceLessThen?:
+         type: number
+       priceMoreThen?:
+        type: number
+ - Paged:
+     queryParameters:
+       offset: number
+       length: number
+
    + +###### Array + +_Array_ is a SEQUENCE containing SCALARs or SEQUENCE containing MAPs in terms of YAML. + +In the following example, the "enum" _Property_ key is highlighted in yellow that has an _Array_ value highlighted blue. + +
    +enum:
+ - White
+ - Black
+ - Colored
+
    + +Another example for an _Array_ definition, a "documentation" _Property_ key has an _Array_ value, which contains two _Objects_ highlighted in green: + +
    +documentation:
+- title: Introduction
+  content: Automated access to books
+
+- title: Licensing
+  content: Please respect copyrights on our books.
+
    + +###### Property Types + +In the merging algorithm the _Property_ types are referred to as _Property Kind_ which can be one of the following (highlighted in **bold**): + +**_Object Property_** - a _Property_ having _Object_ as a value. + +In the following example, "properties" _Property_ is an _Object Property_: + +
    +properties:
+   statusCode: 200
+   responseParameters:
+
    + +**_Array Property_** - a _Property_ having _Array_ of _Objects_ as a value. + +In the following example, "documentation" _Property_ is an _Object Property_: + +
    +documentation:
+- title: Introduction
+  content: Automated access to books
+
+- title: Licensing
+  content: Please respect copyrights on our books.
+
    + +**_Simple property_** - a _Property_ having YAML SCALAR or a SEQUENCE of YAML SCALARS as a value. + +In the following sample "statusCode" and "enum" are simple properties. + +
    +statusCode: 200
+enum:
+ - White
+ - Black
+ - Colored
+
    + +**_Single-value Simple Property_** - a Simple property having YAML SCALAR value. + +
    +statusCode: 200
+
    + +**_Multi-value Simple Property_** - a Simple property having a SEQUENCE of YAML SCALARS as value. + +
    +enum:
+ - White
+ - Black
+ - Colored
+
    + +Exceptions: +* Examples are always _Simple Properties_ despite its ability to have complex YAML samples as values. +* Annotations are always _Simple Properties_ despite potentially having a complex node structure. +* Resource type applications are always _Simple Properties_. +* Trait applications are always _Simple Properties_. +* _Security Schema_ applications are always Simple Properties. + +###### Conflicting Properties + +Conflicting properties are the properties, which can not coexist in the same Object at the same time. + +In the following example both "type" and "properties" _Properties_ can coexist with each other, but the "enum" _Property_ cannot coexist with both "type" and "properties". + +
    +color:
+  type: object
+  properties:
+    name: string
+  enum:
+   - White
+   - Black
+   - Colored
+
    + +###### Ignored properties + +_Ignored Properties_ - the following properties are considered ignored: +"uses" and "usage". + +###### The Trees + +_Master Tree_ - Master file document YAML parsing tree result. +_Extension Tree_ - overlay or extension YAML parsing tree result. +_Target Tree_ - the result tree. + +##### Merging Algorithm: + +Master document and Extension or Overlay are parsed by YAML parser to produce _Master Tree_ and _Extension Tree_. + +_Master Tree_ and _Extension Tree_ are validated, in case of an error the merge process is cancelled. + +All _includes_ are resolved and applied for both _Master Tree_ and _Extension Tree_. + +All _uses_ are resolved and applied for both _Master Tree_ and _Extension Tree_. The trees MUST NOT have _uses_ instructions with the same namespace referring to different files. + +Initially, _Target Tree_ is made equal to the _Master Tree_. + +**Current Extension Tree Object** is set to the _Extension Tree_ root (API). +**Current Target Tree Object** is set to the _Target Tree_ root (API). + +For each **Current Extension Tree Object property** the following is done: + +* If the **property** is an _Ignored Property_, continue to process the next property. +* If the **property** with the same name exists in **Current Target Tree Object**: + * If the **property** and the equally named property in **Current Target Tree Object** have different _Property Kind_: + * The **property** value in the equally named **Current Target Tree Object** property is replaced with its value from **Current Extension Tree Object** property. + * If the **property** is a _Simple Property_ + * If the **property** is a _Single-value Simple Property_, + * The **property** value in the equally named **Current Target Tree Object** property is replaced with its value from **Current Extension Tree Object** property. + * If the **property** is a _Multi-value Simple Property_ + * The **property** value from **Current Extension Tree Object** property is added to the equally named **Current Target Tree Object** property values if no such value already exists. + * If the **property** is an _Object Property_: + * The same _Merging Algorithm_ is recursively performed for **Current Extension Tree Object** being set to the **property** value, and **Current Target Tree Object** being set to the value of the equally named property in **Current Target Tree Object**. + * If the **property** is an _Array Property_: + * _Objects_ from the property value are added to the equally named **Current Target Tree Object** property value. +* If the **property** with the same name does not exist in **Current Target Tree Object**: + * All _Conflicting Properties_ are removed from the **Current Target Tree Object** + * The **property** is added to the **Current Target Tree Object**. + +_Target Tree_ is validated. + +If the _Extension Tree_ is an Overlay, _Target Tree_ is compared to the _Master Tree_. There MUST NOT be any differences, besides listed in the "Allowed differences" table in section [Overlays](#overlays). Otherwise the process is cancelled. + +_Target Tree_ has its resource types and Traits applied. + +_Target Tree_ is being serialized to a document, or returned as the algorithm output. + +## References + +### Normative References + +Berners-Lee, T., Masinter, L., and M. McCahill, "Uniform Resource Locators (URL)", RFC 1738, December 1994. + +Bradner, S., "Key words for use in RFCs to Indicate Requirement Levels", BCP 14, RFC 2119, March 1997. + +Berners-Lee, T., Fielding, R., and L. Masinter, "Uniform Resource Identifiers (URI): Generic Syntax", RFC 2396, August 1998. + +Fielding, R., Gettys, J., Mogul, J., Frystyk, H., Masinter, L., Leach, P., and T. Berners-Lee, "Hypertext Transfer Protocol -- HTTP/1.1", RFC 2616, June 1999. + +Crockford, D., "The application/json Media Type for JavaScript Object Notation (JSON)", RFC 4627, July 2006. + +Dusseault, L. and J. Snell, "PATCH Method for HTTP", RFC 5789, March 2010. + +Gregorio, J., Fielding, R., Hadley, M., Nottingham, M., and D. Orchard, "URI Template", RFC 6570, March 2012. + +Ben Kiki, O., Evans, C., and I. Net, "YAML Aint Markup Language", 2009, . + +### Informative References + +Galiegue, F., Zyp, K., and G. Court, "JSON Schema: core definitions and terminology", 2013, . + +Gruber, J., "Markdown Syntax Documentation", 2004, . + +Fielding, R., "Representational State Transfer (REST)", 2000, . + +Rose, M., "Writing I-Ds and RFCs using XML", RFC 2629, June 1999. + +Rescorla, E. and B. Korver, "Guidelines for Writing RFC Text on Security Considerations", BCP 72, RFC 3552, July 2003. + +Gao, S., Sperberg-McQueen, C., and H. Thompson, "W3C XML Schema Definition Language (XSD) 1.1", 2012, . From 6ee820dcdc02a8d5c3d56ca29bb8ae9e3a07249c Mon Sep 17 00:00:00 2001 From: Christian Vogel Date: Mon, 29 Feb 2016 11:30:47 +0000 Subject: [PATCH 002/241] added link to branch structure in our wiki inside the README file --- README.md | 2 ++ 1 file changed, 2 insertions(+) diff --git a/README.md b/README.md index 97fb56e5..5b4c584b 100644 --- a/README.md +++ b/README.md @@ -27,6 +27,8 @@ You can also directly get in touch with us. Simply send us an email to: info@ram Currently we are working on RC2 inside another branch called `raml-10-rc2`. If you want to fix any spelling or grammar mistake, or an error in our examples, please fork that branch, make your edits, and then submit a pull request. +More information around the current branch structure can be viewed [here](https://github.com/raml-org/raml-spec/wiki/RAML-1.0-RC2---Plan#branch-structure) + ## Licensing [Branding Guidelines](http://raml.org/licensing.html) From a8cc116ee7a658866f872f1867f35905ac7f42d6 Mon Sep 17 00:00:00 2001 From: Christian Vogel Date: Mon, 29 Feb 2016 11:51:22 +0000 Subject: [PATCH 003/241] fix issue 257 - type in section schema miles -> files --- versions/raml-08/raml-08.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/versions/raml-08/raml-08.md b/versions/raml-08/raml-08.md index a3fec536..9e4295f5 100644 --- a/versions/raml-08/raml-08.md +++ b/versions/raml-08/raml-08.md @@ -935,7 +935,7 @@ The *schema* key CANNOT be specified if a body's media type is *application/x-ww All parsers of RAML MUST be able to interpret JSON Schema [JSON_SCHEMA] and XML Schema [XML_SCHEMA]. -Schema MAY be declared inline or in an external file. However, if the schema is sufficiently large so as to make it difficult for a person to read the API definition, or the schema is reused across multiple APIs or across multiple miles in the same API, the !include user-defined data type SHOULD be used instead of including the content inline. +Schema MAY be declared inline or in an external file. However, if the schema is sufficiently large so as to make it difficult for a person to read the API definition, or the schema is reused across multiple APIs or across multiple files in the same API, the !include user-defined data type SHOULD be used instead of including the content inline. This example shows an inline schema declaration. From 34652b0a08694d925f9bdf2018a5941b42ff52b7 Mon Sep 17 00:00:00 2001 From: Christian Vogel Date: Mon, 29 Feb 2016 12:07:59 +0000 Subject: [PATCH 004/241] fix issue 260 - typos in resource references user vs users --- versions/raml-08/raml-08.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/versions/raml-08/raml-08.md b/versions/raml-08/raml-08.md index 9e4295f5..3719fe32 100644 --- a/versions/raml-08/raml-08.md +++ b/versions/raml-08/raml-08.md @@ -582,7 +582,7 @@ baseUriParameters: enum: [ "api-content" ] ``` -In a resource structure of resources and nested resources with their methods, the most specific baseUriParameter fully overrides any baseUriParameter definition made before. In the following example the resource `/user/{userId}/image` overrides the definition made in `/users`. +In a resource structure of resources and nested resources with their methods, the most specific baseUriParameter fully overrides any baseUriParameter definition made before. In the following example the resource `/users/{userId}/image` overrides the definition made in `/users`. ``` #%RAML 0.8 @@ -601,7 +601,7 @@ baseUri: https://{apiDomain}.someapi.com enum: [ "static" ] ``` -In the following example, the `PUT` method overrides the definition made in `/user/{userId}/image`. +In the following example, the `PUT` method overrides the definition made in `/users/{userId}/image`. ``` #%RAML 0.8 From 59b6816d44b996af890e03b691c44ad9d9d2883b Mon Sep 17 00:00:00 2001 From: Christian Vogel Date: Mon, 29 Feb 2016 12:21:27 +0000 Subject: [PATCH 005/241] fix and close issue #244; add displayName to securitySchemes and remove displayName and description from describedBy --- versions/raml-10/raml-10.md | 3 +-- 1 file changed, 1 insertion(+), 2 deletions(-) diff --git a/versions/raml-10/raml-10.md b/versions/raml-10/raml-10.md index 9f362570..f90a2e41 100644 --- a/versions/raml-10/raml-10.md +++ b/versions/raml-10/raml-10.md @@ -2211,6 +2211,7 @@ Security scheme is declared as follows: |Property |Description| |:----------|:----------| | type | The security schemes property MUST be used to specify an API's security mechanisms, including the required settings and the authentication methods that the API supports. one authentication method is allowed if the API supports them. The value MUST be one of the following: OAuth 1.0, OAuth 2.0, Basic Authentication, Digest Authentication, Pass Through, x-<other> +| displayName? | An alternate, human-friendly name for the security scheme part | description? | The description MAY be used to describe a security scheme. | describedBy? | A description of the request components related to Security that are determined by the scheme: the headers, query parameters or responses. As a best practice, even for standard security schemes, API designers SHOULD describe these properties of security schemes. Including the security scheme description completes an API documentation. See explanation about [describedBy](#describedBy) for more information. | settings? | The settings attribute MAY be used to provide security scheme-specific information. The required attributes vary depending on the type of security scheme is being declared. It describes the minimum set of properties which any processing application MUST provide and validate if it chooses to implement the security scheme. Processing applications MAY choose to recognize other properties for things such as token lifetime, preferred cryptographic algorithms, and more. See explanation about [seetings](#settings) for more information. @@ -2277,8 +2278,6 @@ The value of the **describedBy** property is defined as follows: | queryParameters? | Query parameters, used by the schema in order to authorize the request. Mutually exclusive with queryString. See section [Query Strings and Query Parameters](#query-strings-and-query-parameters) for more information. | queryString? | Specifies the query string, used by the schema in order to authorize the request. Mutually exclusive with queryParameters. See section [Query Strings and Query Parameters](#query-strings-and-query-parameters) for more information. | responses? | Optional array of responses, describing the possible responses that could be sent. See section [Responses](#responses) for more information. -| displayName? | An alternate, human-friendly name for the security scheme part -| description? | A longer, human-friendly description of the security scheme part | (<annotationName>)? | Annotations to be applied to this security scheme part. Annotations are any property whose key begins with "(" and ends with ")" and whose name (the part between the beginning and ending parentheses) is a declared annotation name. See section [Annotations](#annotations) for more information. #### Settings From bbb6d321af3ae641c4cbfdcf16bb198409b65431 Mon Sep 17 00:00:00 2001 From: Christian Vogel Date: Mon, 29 Feb 2016 12:21:27 +0000 Subject: [PATCH 006/241] fix and close issue #244; add displayName to securitySchemes and remove displayName and description from describedBy --- versions/raml-10/raml-10.md | 5 ++--- 1 file changed, 2 insertions(+), 3 deletions(-) diff --git a/versions/raml-10/raml-10.md b/versions/raml-10/raml-10.md index 9f362570..94698815 100644 --- a/versions/raml-10/raml-10.md +++ b/versions/raml-10/raml-10.md @@ -2211,9 +2211,10 @@ Security scheme is declared as follows: |Property |Description| |:----------|:----------| | type | The security schemes property MUST be used to specify an API's security mechanisms, including the required settings and the authentication methods that the API supports. one authentication method is allowed if the API supports them. The value MUST be one of the following: OAuth 1.0, OAuth 2.0, Basic Authentication, Digest Authentication, Pass Through, x-<other> +| displayName? | An alternate, human-friendly name for the security scheme. | description? | The description MAY be used to describe a security scheme. | describedBy? | A description of the request components related to Security that are determined by the scheme: the headers, query parameters or responses. As a best practice, even for standard security schemes, API designers SHOULD describe these properties of security schemes. Including the security scheme description completes an API documentation. See explanation about [describedBy](#describedBy) for more information. -| settings? | The settings attribute MAY be used to provide security scheme-specific information. The required attributes vary depending on the type of security scheme is being declared. It describes the minimum set of properties which any processing application MUST provide and validate if it chooses to implement the security scheme. Processing applications MAY choose to recognize other properties for things such as token lifetime, preferred cryptographic algorithms, and more. See explanation about [seetings](#settings) for more information. +| settings? | The settings attribute MAY be used to provide security scheme-specific information. The required attributes vary depending on the type of security scheme is being declared. It describes the minimum set of properties which any processing application MUST provide and validate if it chooses to implement the security scheme. Processing applications MAY choose to recognize other properties for things such as token lifetime, preferred cryptographic algorithms, and more. See explanation about [settings](#settings) for more information. An optional **securitySchemes** property is defined for RAML document root. As value it has an object whose properties map security scheme names to security scheme declarations. @@ -2277,8 +2278,6 @@ The value of the **describedBy** property is defined as follows: | queryParameters? | Query parameters, used by the schema in order to authorize the request. Mutually exclusive with queryString. See section [Query Strings and Query Parameters](#query-strings-and-query-parameters) for more information. | queryString? | Specifies the query string, used by the schema in order to authorize the request. Mutually exclusive with queryParameters. See section [Query Strings and Query Parameters](#query-strings-and-query-parameters) for more information. | responses? | Optional array of responses, describing the possible responses that could be sent. See section [Responses](#responses) for more information. -| displayName? | An alternate, human-friendly name for the security scheme part -| description? | A longer, human-friendly description of the security scheme part | (<annotationName>)? | Annotations to be applied to this security scheme part. Annotations are any property whose key begins with "(" and ends with ")" and whose name (the part between the beginning and ending parentheses) is a declared annotation name. See section [Annotations](#annotations) for more information. #### Settings From f780b4293d4765104cb94a35f2a51e1b61801c15 Mon Sep 17 00:00:00 2001 From: Christian Vogel Date: Mon, 29 Feb 2016 14:40:12 +0000 Subject: [PATCH 007/241] incorporate Uri's commit to remove part from the description for displayName --- versions/raml-10/raml-10.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/versions/raml-10/raml-10.md b/versions/raml-10/raml-10.md index a5ab1f42..94698815 100644 --- a/versions/raml-10/raml-10.md +++ b/versions/raml-10/raml-10.md @@ -2211,7 +2211,7 @@ Security scheme is declared as follows: |Property |Description| |:----------|:----------| | type | The security schemes property MUST be used to specify an API's security mechanisms, including the required settings and the authentication methods that the API supports. one authentication method is allowed if the API supports them. The value MUST be one of the following: OAuth 1.0, OAuth 2.0, Basic Authentication, Digest Authentication, Pass Through, x-<other> -| displayName? | An alternate, human-friendly name for the security scheme part +| displayName? | An alternate, human-friendly name for the security scheme. | description? | The description MAY be used to describe a security scheme. | describedBy? | A description of the request components related to Security that are determined by the scheme: the headers, query parameters or responses. As a best practice, even for standard security schemes, API designers SHOULD describe these properties of security schemes. Including the security scheme description completes an API documentation. See explanation about [describedBy](#describedBy) for more information. | settings? | The settings attribute MAY be used to provide security scheme-specific information. The required attributes vary depending on the type of security scheme is being declared. It describes the minimum set of properties which any processing application MUST provide and validate if it chooses to implement the security scheme. Processing applications MAY choose to recognize other properties for things such as token lifetime, preferred cryptographic algorithms, and more. See explanation about [settings](#settings) for more information. From 57ab80f745f9d6f8f882e7ece6d24ee989d7eb88 Mon Sep 17 00:00:00 2001 From: Christian Vogel Date: Mon, 29 Feb 2016 15:38:22 +0000 Subject: [PATCH 008/241] clarify how traits, resource types, and security schemes behave on nested resources --- versions/raml-10/raml-10.md | 7 ++++--- 1 file changed, 4 insertions(+), 3 deletions(-) diff --git a/versions/raml-10/raml-10.md b/versions/raml-10/raml-10.md index 94698815..08a5b0b2 100644 --- a/versions/raml-10/raml-10.md +++ b/versions/raml-10/raml-10.md @@ -2047,9 +2047,9 @@ It is important to note that this feature applies only to object-valued properti ### Applying Resource Types and Traits -The OPTIONAL **type** property applies a resource type to a resource, so that the resource inherits the resource type's characteristics. The value of the **type** property is either a) a name of a resource type declared in the resourceTypes declaration, or b) an inline (anonymous) resource type declaration. +The OPTIONAL **type** property applies a resource type to a resource, so that the resource inherits the resource type's characteristics. The value of the **type** property is either a) a name of a resource type declared in the resourceTypes declaration, or b) an inline (anonymous) resource type declaration. Resource type definitions MUST NOT incorporate nested resources; they cannot be used to generate nested resources when they are applied to a resource, and they do not apply to its existing nested resources. -The OPTIONAL **is** property applies any number of traits to a method, so that the method inherits the trait's or traits' characteristics. The value of the is attribute is an array of any number of elements, each of which is either a) a name of a trait declared in the traits declaration, or b) an inline (anonymous) trait declaration. +The OPTIONAL **is** property applies any number of traits to a method, so that the method inherits the trait's or traits' characteristics. The value of the is attribute is an array of any number of elements, each of which is either a) a name of a trait declared in the traits declaration, or b) an inline (anonymous) trait declaration. Trait definitions MUST NOT incorporate nested resources. A trait may also be applied to a resource by using the **is** key, which is equivalent to applying the trait to all methods for that resource, whether declared explicitly in the resource definition or inherited from a resource type. @@ -2217,6 +2217,7 @@ Security scheme is declared as follows: | settings? | The settings attribute MAY be used to provide security scheme-specific information. The required attributes vary depending on the type of security scheme is being declared. It describes the minimum set of properties which any processing application MUST provide and validate if it chooses to implement the security scheme. Processing applications MAY choose to recognize other properties for things such as token lifetime, preferred cryptographic algorithms, and more. See explanation about [settings](#settings) for more information. An optional **securitySchemes** property is defined for RAML document root. + As value it has an object whose properties map security scheme names to security scheme declarations. Each authentication pattern supported by the API must be expressed as component of **securitySchemes** property value. @@ -2485,7 +2486,7 @@ securitySchemes: securedBy: [null, oauth_2_0] ``` -A resource can also be applied a list of security schemes using the **securedBy** attribute. This specifies that all methods of this particular resource (unless they have their own securedBy attribute) can be authenticated by any mentioned security scheme. Value of resources attribute overrides that of the root attribute. +A resource can also be applied a list of security schemes using the **securedBy** attribute. This specifies that all methods of this particular resource (unless they have their own securedBy attribute) can be authenticated by any mentioned security scheme. Value of resources attribute overrides that of the root attribute. Security Schemes applied to a resource MUST NOT incorporate nested resources; they do not apply to its existing nested resources. Applying a security scheme to a method overrides security schemes applied to the API and resources having the method as sibling. From e437dfdda5ecfa6e0fcdd80cb924793572b772bc Mon Sep 17 00:00:00 2001 From: Christian Vogel Date: Tue, 1 Mar 2016 15:09:38 +0000 Subject: [PATCH 009/241] commit closes issue #228 - change occurrences of the keyword to --- versions/raml-10/raml-10.md | 12 ++++++------ 1 file changed, 6 insertions(+), 6 deletions(-) diff --git a/versions/raml-10/raml-10.md b/versions/raml-10/raml-10.md index 94698815..f9307e52 100644 --- a/versions/raml-10/raml-10.md +++ b/versions/raml-10/raml-10.md @@ -2963,7 +2963,7 @@ resourceTypes: API definitions may need to be extended in a variety of ways for different needs. Annotations allow for adding metadata beyond that which is standardized in this RAML specification. Another set of needs is satisfied by overlaying standard or non-standard metadata on top of an existing API definition without changing its behavior, for example to specify implementation details or provide a translation of human-oriented documentation into different languages. Yet another set of needs requires extending an API definition by adding to its behavior or overriding certain aspects. RAML provides two mechanisms for doing so: overlays and extensions. -Overlays and extensions are RAML documents that add or override properties of a RAML API definition. The first line of an overlay or extension document MUST begin with the text _#%RAML 1.0 Overlay_ or _#%RAML 1.0 Extension_, respectively, followed by nothing but the end of the line. An overlay or extension document MUST contain a root-level masterRef property whose value MUST be the location of a valid RAML API definition, or another overlay or extension; the location is specified equivalently to the location specified in the value of an !include tag (as an absolute or relative path or as a URL). The document specified in the masterRef property is called the master RAML document. +Overlays and extensions are RAML documents that add or override properties of a RAML API definition. The first line of an overlay or extension document MUST begin with the text _#%RAML 1.0 Overlay_ or _#%RAML 1.0 Extension_, respectively, followed by nothing but the end of the line. An overlay or extension document MUST contain a root-level `extends` property whose value MUST be the location of a valid RAML API definition, or another overlay or extension; the location is specified equivalently to the location specified in the value of an !include tag (as an absolute or relative path or as a URL). The document specified in the `extends` property is called the master RAML document. The remainder of an overlay or extension document follows the same rules as a RAML API definition, but with certain restrictions in case of an overlay, as discussed in section about [Overlays](#overlays). @@ -3009,7 +3009,7 @@ documentation: ```yaml #%RAML 1.0 Overlay usage: Spanish localization -masterRef: librarybooks.raml +extends: librarybooks.raml documentation: - title: Introducción content: El acceso automatizado a los libros @@ -3022,7 +3022,7 @@ documentation: ```yaml #%RAML 1.0 Overlay usage: Hints for monitoring the library books API -masterRef: librarybooks.raml +extends: librarybooks.raml annotationTypes: monitor: parameters: @@ -3050,7 +3050,7 @@ The following examples build on the examples in the overlays section above, by a ```yaml #%RAML 1.0 Extension usage: Add administrative functionality -masterRef: librarybooks.raml +extends: librarybooks.raml /books: post: description: Add a new book to the collection @@ -3059,7 +3059,7 @@ masterRef: librarybooks.raml ```yaml #%RAML 1.0 Overlay usage: Spanish localization for admin functionality -masterRef: librarybooks.raml +extends: librarybooks.raml /books: post: description: A?adir un nuevo libro para la colecci?n @@ -3068,7 +3068,7 @@ masterRef: librarybooks.raml ```yaml #%RAML 1.0 Extension usage: The location of the public instance of the Piedmont library API -masterRef: librarybooks.raml +extends: librarybooks.raml baseUri: http://api.piedmont-library.com ``` From 4c9234e9e72d04d7ecbb58e0ba1db1a6b58b65b8 Mon Sep 17 00:00:00 2001 From: Christian Vogel Date: Tue, 1 Mar 2016 15:36:19 +0000 Subject: [PATCH 010/241] modified template uris from level 1 to also support level 2; as well as introduced a global definition inside Definitions and Terminology chapter. I also added a few more that can be linked throughout the document. --- versions/raml-10/raml-10.md | 36 +++++++++++++++++++++++++----------- 1 file changed, 25 insertions(+), 11 deletions(-) diff --git a/versions/raml-10/raml-10.md b/versions/raml-10/raml-10.md index f9307e52..3ea42d0e 100644 --- a/versions/raml-10/raml-10.md +++ b/versions/raml-10/raml-10.md @@ -19,16 +19,30 @@ The keywords "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SH ## Definitions and Terminology -For this specification, **API definition** will be used to denote the description of an API using this specification and **RAML Specification** refers to the current document. +### General -**REST** is used in the context of an API implemented using some or all of the principles of REST. The REST acronym stands for Representational State Transfer and was first introduced and defined in 2000 by Roy Fielding in his doctoral dissertation [REST]. +For this specification, **API definition** is used to denote the description of an API using this specification and **RAML Specification** refers to the current document. -A **resource** is the conceptual mapping to an entity or set of entities. +**REST** is used in the context of an API implemented using some or all of the principles of REST. The REST acronym stands for Representational State Transfer and was first introduced and defined in 2000 by Roy Fielding in his doctoral dissertation [REST](http://www.ics.uci.edu/~fielding/pubs/dissertation/rest_arch_style.htm). -Throughout this specification, **markdown** means [GitHub-Flavored Markdown](https://help.github.com/articles/github-flavored-markdown/). +A **resource** is the conceptual mapping to an entity or set of entities. Optional properties are indicated with trailing question marks (e.g. **description?**). +### Markdown + +Throughout this specification, **Markdown** means [GitHub-Flavored Markdown](https://help.github.com/articles/github-flavored-markdown/). + +### Media Types + +The value of a specific media type property MUST conform to the media type specification in [RFC6838](https://tools.ietf.org/html/rfc6838). + +### Template URI + +A template URI refers to any URI parameters using curly brackets ({}) to mark a section inside a resource's relative URI as variable element. + +RAML fully supports Level 2 as defined in [RFC6570](https://tools.ietf.org/html/rfc6570) for any template URIs. + ## Introduction This specification describes the RESTful API Modeling Language (RAML). RAML is a human- and machine-readable language for the definition of a RESTful application programming interface (API). RAML is designed to improve the specification of such interfaces by providing a format that can serve as a useful contract between the API provider and the API consumers, for example to facilitate providing user documentation and source code stubs for client and server implementations, thereby streamlining and enhancing the definition and development of interoperable applications that utilize RESTful APIs. @@ -130,7 +144,7 @@ The following table enumerates the possible properties at the root of a RAML doc | uses? | Importing external libraries that can be used within the API. See section [Libraries](#libraries) for more information. | title | Short plain-text label for the API | version? | The version of the API, e.g. "v1" -| baseUri? | A URI that's to be used as the base of all the resources' URIs. Often used as the base of the URL of each resource, containing the location of the API. Can be a template URI. See section [Base URI and Base URI Parameters](#base-uri-and-base-uri-parameters) for more information. +| baseUri? | A URI that's to be used as the base of all the resources' URIs. Often used as the base of the URL of each resource, containing the location of the API. Can be a [template URI](#template-uri). See section [Base URI and Base URI Parameters](#base-uri-and-base-uri-parameters) for more information. | baseUriParameters? | Named parameters used in the baseUri (template). See section [Base URI and Base URI Parameters](#base-uri-and-base-uri-parameters) for more information. | protocols? | The protocols supported by the API. The protocols property MUST contain one or more of the supported protocols: "HTTP", "HTTPS". (case-insensitive). | mediaType? | The default media type to use for request and response bodies (payloads), e.g. "application/json" @@ -183,9 +197,9 @@ documentation: ### Base URI and Base URI Parameters -The OPTIONAL **baseUri** property specifies a URI as an identifier for the API as a whole, and MAY be used the specify the URL at which the API is served (its service endpoint), and which forms the base of the URLs of each of its resources. The baseUri property's value is a string that MUST conform to the URI specification [RFC2396](https://www.ietf.org/rfc/rfc2396.txt) or a Level 1 Template URI as defined in [RFC 6570](https://tools.ietf.org/html/rfc6570). +The OPTIONAL **baseUri** property specifies a URI as an identifier for the API as a whole, and MAY be used the specify the URL at which the API is served (its service endpoint), and which forms the base of the URLs of each of its resources. The baseUri property's value is a string that MUST conform to the URI specification [RFC2396](https://www.ietf.org/rfc/rfc2396.txt) or a [Template URI](#template-uri). -If the baseUri value is a Level 1 Template URI, the following reserved base URI parameter is available. +If the baseUri value is a [Template URI](#template-uri), the following reserved base URI parameter is available. | URI Parameter | Value | |:----------|:----------| @@ -193,7 +207,7 @@ If the baseUri value is a Level 1 Template URI, the following reserved base URI Any other URI template variables appearing in the baseUri MAY be described explicitly within a **baseUriParameters** property at the root of the API definition. The baseUriParameters property has the same structure and semantics as the uriParameters property on a resource property, except that it specifies parameters in the base URI rather than a resource's relative URI. See the section [Template URIs and URI parameters](#template-uris-and-uri-parameters) for information about the uriParameters property. -The following example RAML API definition uses a Level 1 Template URI as the base URI. +The following example RAML API definition uses a [Template URI](#template-uri) as the base URI. ```yaml #%RAML 1.0 @@ -1482,7 +1496,7 @@ The OPTIONAL **description** property can be used to provide a longer descriptio ### Template URIs and URI Parameters -Template URIs containing URI parameters can be used to define a resource's relative URI when it contains variable elements. The following example shows a top-level resource with a key /jobs and a nested resource with a key /{jobId}. +[Template URIs](#template-uri) containing URI parameters can be used to define a resource's relative URI when it contains variable elements. The following example shows a top-level resource with a key /jobs and a nested resource with a key /{jobId}. ```yaml #%RAML 1.0 @@ -1495,13 +1509,13 @@ baseUri: https://app.zencoder.com/api/{version} description: A specific job, a member of the jobs collection ``` -The OPTIONAL **uriParameters** property is used to explicitly specify URI parameters in a template URI. The value of the uriParameters property is an object, specifically a [properties declaration](#property-declarations), as is the value of the properties object of a type declaration. Each property in this declaration object is referred to as a **URI parameter declaration**. The name of each such property corresponds to the name of a parameter in the template URI, while its value specifies the URI parameter's type, as the name of a type or an inline type declaration. +The OPTIONAL **uriParameters** property is used to explicitly specify URI parameters in a [Template URI](#template-uri). The value of the uriParameters property is an object, specifically a [properties declaration](#property-declarations), as is the value of the properties object of a type declaration. Each property in this declaration object is referred to as a **URI parameter declaration**. The name of each such property corresponds to the name of a parameter in the [Template URI](#template-uri), while its value specifies the URI parameter's type, as the name of a type or an inline type declaration. Every property in a uriParameters declaration MUST correspond exactly to the name of a URI parameter in the resource's relative URI. But not every URI parameter in the resource's relative URI must be explicitly specified in the uriParameters property. Every parameter in the relative URI not specified in the uriParameters property MUST still be treated as a URI parameter, of type string, and required. Just as is the case for [the baseUriParameters root property](#base-uri-and-base-uri-parameters), the version parameter is a reserved parameter name in the uriParameters properties declaration, with a value corresponding to the value of the version root-level property. -The example below shows two top-level resources (/user and /users) and a nested resource specified by its template URI, /{userId}. The URI parameter userId is explicitly declared, and given a description and an integer type. +The example below shows two top-level resources (/user and /users) and a nested resource specified by its [Template URI](#template-uri), /{userId}. The URI parameter userId is explicitly declared, and given a description and an integer type. ```yaml #%RAML 1.0 From fe612d2a7d475bb95b45e30a6e4a918dd1ca6dfe Mon Sep 17 00:00:00 2001 From: Christian Vogel Date: Wed, 2 Mar 2016 15:36:26 +0000 Subject: [PATCH 011/241] closes issue #268 - adding more details to the available functions for resource type parameters --- versions/raml-10/raml-10.md | 20 ++++++++++---------- 1 file changed, 10 insertions(+), 10 deletions(-) diff --git a/versions/raml-10/raml-10.md b/versions/raml-10/raml-10.md index f9307e52..27969293 100644 --- a/versions/raml-10/raml-10.md +++ b/versions/raml-10/raml-10.md @@ -1944,16 +1944,16 @@ Parameter values MAY further be transformed by applying one of the following fun | Function | Definition | |:---------|:-----------| -| !singularize | The !singularize function MUST act on the value of the parameter by a locale-specific singularization of its original value. The only locale supported by this version of RAML is United States English. -| !pluralize | The !pluralize function MUST act on the value of the parameter by a locale-specific pluralization of its original value. The only locale supported by this version of RAML is United States English. -| !uppercase | effect: `userId --> USERID` -| !lowercase | effect: `userId --> userid` -| !lowercamelcase | effect: `userId --> userId` -| !uppercamelcase | effect: `userId --> UserId` -| !lowerunderscorecase | effect: `userId --> user_id` -| !upperunderscorecase | effect: `userId --> USER_ID` -| !lowerhyphencase | `effect: userId --> user-id` -| !upperhyphencase | effect: userId --> USER-ID` +| !singularize | The !singularize function MUST act on the value of the parameter by a locale-specific singularization of its original value. The only locale supported by this version of RAML is United States English.

    for example: `users --> user` +| !pluralize | The !pluralize function MUST act on the value of the parameter by a locale-specific pluralization of its original value. The only locale supported by this version of RAML is United States English.

    for example: `user --> users` +| !uppercase | The !uppercase function MUST convert the value of the parameter to uppercase letters.

    for example: `userId --> USERID` +| !lowercase | The !lowercase function MUST convert the value of the parameter to lowercase letters.

    for example: `userId --> userid` +| !lowercamelcase | The !lowercamelcase function MUST convert the value of the parameter to camel case where the first letter is lowercase.

    for example: `userId --> userId` +| !uppercamelcase | The !uppercamelcase function MUST convert the value of the parameter to camel case where the first letter is uppercase.

    for example: `userId --> UserId` +| !lowerunderscorecase | The !lowerunderscorecase function MUST convert the value of the parameter to lowercase letters and if the value is a compound word the function MUST add an additional underscore between each word except when there is already one present.

    for example: `userId --> user_id` +| !upperunderscorecase | The !upperunderscorecase function MUST convert the value of the parameter to uppercase letters and if the value is a compound word the function MUST add an additional underscore between each word except when there is already one present.

    for example: `userId --> USER_ID` +| !lowerhyphencase | The !lowerhyphencase function MUST convert the value of the parameter to lowercase letters and if the value is a compound word the function MUST add an additional hyphen between each word except when there is already one present.

    for example: `userId --> user-id` +| !upperhyphencase | The !upperhyphencase function MUST convert the value of the parameter to uppercase letters and if the value is a compound word the function MUST add an additional hyphen between each word except when there is already one present.

    for example: `userId --> USER-ID` To apply these functions, append them to the parameter name within the double angle brackets, separated from the parameter name with a pipe ("|") character and optional whitespace padding. Here is an example that uses both functions as well as reserved parameters: From 321f2c3f4a9c22e50f64ac2bbfaddfe7e4f58afd Mon Sep 17 00:00:00 2001 From: Christian Vogel Date: Thu, 3 Mar 2016 19:34:24 +0000 Subject: [PATCH 012/241] closes issue 246 - clarifies behaviour of default media type --- versions/raml-10/raml-10.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/versions/raml-10/raml-10.md b/versions/raml-10/raml-10.md index f9307e52..13a8f190 100644 --- a/versions/raml-10/raml-10.md +++ b/versions/raml-10/raml-10.md @@ -234,8 +234,6 @@ The media types expected from API requests that contain a body, and returned by The value of the mediaType property MUST be a media type string conforming to the media type specification in [RFC6838](https://tools.ietf.org/html/rfc6838). -For any combination of resource, operation, and request or response in the API, if a media type is specified as a key of the body property for that resource and operation and request or response, or if a media type is specified in the mediaType property, the body MUST conform to the specified media type. - This example shows a RAML snippet for an API that accepts and returns JSON-formatted bodies. If the remainder of this API's specification doesn't explicitly specify another media type, this API only accepts and returns JSON-formatted bodies. ```yaml @@ -246,6 +244,8 @@ baseUri: https://api.stormpath.com/{version} mediaType: application/json ``` +The default media type can be overridden by defining a `mediaType` node explicitly to a [body](#bodies) of an API request or response. + ### Default Security The security schemes to be applied to every method of every resource in the API can be defaulted by specifying the OPTIONAL **securedBy** property. Its value is an array of security scheme names. If this property is specified, every method of every resource is protected by the specified security schemes. See section [Applying Security Schemes](#applying-security-schemes) for more information, including how to resolve application of multiple security schemes via inheritance. @@ -1747,7 +1747,7 @@ baseUri: https://api.twitter.com/{version} The HTTP request **body** for a method is specified using the OPTIONAL body property. For example, to create a resource using a POST or PUT, the body of the request would usually include the details of the resource to be created. -The value of the body property is termed a **body declaration**. The body declaration is an object whose property names are the valid media types of the request body and whose property values are the corresponding data type declaration or data type name describing the request body. If a default media type has been declared at the root of the API via the mediaType property, then the body declaration may alternatively be directly the data type declaration or data type name describing the request body for that media type. +The value of the body property is termed a **body declaration**. The body declaration is an object whose property names are the valid media types of the request body and whose property values are the corresponding data type declaration or data type name describing the request body. If a [default media type](#default-media-type) has been declared at the root of the API via the mediaType property, then the body declaration may alternatively be directly the data type declaration or data type name describing the request body for that media type. In the first case above, when the property names represent media types, each property name MUST be a media type string conforming to the media type specification in [RFC6838](#https://tools.ietf.org/html/rfc6838). From c957c8b112490cccaaeb80531f0e126f89b2414c Mon Sep 17 00:00:00 2001 From: Christian Vogel Date: Thu, 3 Mar 2016 19:38:34 +0000 Subject: [PATCH 013/241] closes issue 270 - change description when the example and examples property is available --- versions/raml-10/raml-10.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/versions/raml-10/raml-10.md b/versions/raml-10/raml-10.md index 13a8f190..725d9c61 100644 --- a/versions/raml-10/raml-10.md +++ b/versions/raml-10/raml-10.md @@ -386,8 +386,8 @@ declarations may have; certain type declarations may have other properties. |:----------|:----------| | schema? | Alias for the equivalent "type" property, for compatibility with RAML 0.8. Deprecated - API definitions should use the "type" property, as the "schema" alias for that property name may be removed in a future RAML version. The "type" property allows for XML and JSON schemas. | type? | A base type which the current type extends, or more generally a type expression. -| example? | An example of an instance of this type. This can be used, e.g., by documentation generators to generate sample values for an object of this type. Cannot be present if the examples property is present. -| examples? | An object containing named examples of instances of this type. This can be used, e.g., by documentation generators to generate sample values for an object of this type. Cannot be present if the examples property is present. See section [Examples](#examples) for more information. +| example? | An example of an instance of this type. This can be used, e.g., by documentation generators to generate sample values for an object of this type. The `example` property MUST not be available when the `examples` property is already defined. +| examples? | An object containing named examples of instances of this type. This can be used, e.g., by documentation generators to generate sample values for an object of this type. The `examples` property MUST not be available when the `example` property is already defined. See section [Examples](#examples) for more information. | displayName? | An alternate, human-friendly name for the type | description? | A longer, human-friendly description of the type | (<annotationName>)? | Annotations to be applied to this type. Annotations are any property whose key begins with "(" and ends with ")" and whose name (the part between the beginning and ending parentheses) is a declared annotation name. See section on [Annotations](#annotations) for more information. From bd2ba1dc2e94adf68bef5d28cc0e929e4b7b67dd Mon Sep 17 00:00:00 2001 From: Christian Vogel Date: Mon, 7 Mar 2016 10:48:25 +0000 Subject: [PATCH 014/241] changed displayName to description in some examples where displayName was used in HTTP methods which is not allowed. Closes #136 --- versions/raml-08/raml-08.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/versions/raml-08/raml-08.md b/versions/raml-08/raml-08.md index 3719fe32..913b5888 100644 --- a/versions/raml-08/raml-08.md +++ b/versions/raml-08/raml-08.md @@ -619,9 +619,9 @@ baseUri: https://{apiDomain}.someapi.com apiDomain: enum: [ "static" ] get: - displayName: retrieve a user's picture + description: retrieve a user's picture put: - displayName: update a user's picture + description: update a user's picture baseUriParameters: apiDomain: enum: [ "content-update" ] From f8cc3e245ff1f096189f8e640d0a130a97ef0567 Mon Sep 17 00:00:00 2001 From: Christian Vogel Date: Mon, 7 Mar 2016 10:51:40 +0000 Subject: [PATCH 015/241] Fixed example that introduced unallowed description. Closes #191 --- versions/raml-08/raml-08.md | 2 -- 1 file changed, 2 deletions(-) diff --git a/versions/raml-08/raml-08.md b/versions/raml-08/raml-08.md index 913b5888..a15ff74c 100644 --- a/versions/raml-08/raml-08.md +++ b/versions/raml-08/raml-08.md @@ -1050,8 +1050,6 @@ For APIs without *a priori* knowledge of the response types for their responses, 200: body: "*/*": - description: | - Returns the media file. ``` Responses MAY contain a *description* property that further clarifies why the response was emitted. Response descriptions are particularly useful for describing error conditions. From 4a03d2ff45c0e50dbe315dd73e862d4139761bd9 Mon Sep 17 00:00:00 2001 From: Christian Vogel Date: Mon, 7 Mar 2016 11:22:19 +0000 Subject: [PATCH 016/241] Add an example and more clarification to how URI parameter get serialized. Closes #206 --- versions/raml-10/raml-10.md | 28 ++++++++++++++++++++++++---- 1 file changed, 24 insertions(+), 4 deletions(-) diff --git a/versions/raml-10/raml-10.md b/versions/raml-10/raml-10.md index f9307e52..45535513 100644 --- a/versions/raml-10/raml-10.md +++ b/versions/raml-10/raml-10.md @@ -120,7 +120,7 @@ The following table enumerates the possible properties at the root of a RAML doc | Property | Description | |:----------|:----------| | description? | A longer, human-friendly description of the API -| (<annotationName>)? | Annotations to be applied to this API. Annotations are any property whose key begins with "(" and ends with ")" and whose name (the part between the beginning and ending parentheses) is a declared annotation name. See section [Annotations](#annotation) for more information. +| (<annotationName>)? | Annotations to be applied to this API. Annotations are any property whose key begins with "(" and ends with ")" and whose name (the part between the beginning and ending parentheses) is a declared annotation name. See section [Annotations](#annotations) for more information. | schemas? | Alias for the equivalent "types" property, for compatibility with RAML 0.8. Deprecated - API definitions should use the "types" property, as the "schemas" alias for that property name may be removed in a future RAML version. The "types" property allows for XML and JSON schemas. | types? | Declarations of (data) types for use within this API. See section [RAML Data Types](#raml-data-types) for more information. | traits? | Declarations of traits for use within this API. See section [Resource Types and Traits](#resource-types-and-traits) for more information. @@ -1520,7 +1520,27 @@ baseUri: https://api.github.com type: integer ``` -If a URI parameter declaration specifies an array or object type for the value of the header, or if it specifies a union type of non-scalar types, then processors MUST default to treating the format of the URI parameter value as JSON in applying the type to instances of that URI parameter. They MAY allow other treatments based on annotations. +If a URI parameter declaration specifies an array, object, or union of non-scalar types, then processors MUST default to treating the format of the URI parameter value as JSON in applying the type to instances of that URI parameter. The following demonstrates an extreme example of the expected behavior. + +```yaml +#%RAML 1.0 +title: Serialization API + +/users: + description: All users + /{userIds}: + description: A specific user + uriParameters: + userIds: + description: A list of userIds + type: array + items: + type: string + minLength: 1 + uniqueItems: true +``` + +In the example above, the URI parameter `userIds` is an array of ids. Let us assume the array should contain `[blue,green]` which then, on the wire may look as: `/users/%5B%22blue%22,%22green%22%5D/`. If a URI parameter declaration specifies a non-string scalar type for the value of the header, the standard serialization rules for types MUST be invoked in applying the type to instances of that URI parameter. @@ -1567,7 +1587,7 @@ In a RESTful API, methods are operations that are performed on a resource. The O |:--------|:------------| | displayName? | An alternate, human-friendly name for the method (in the resource's context). | description? | A longer, human-friendly description of the method (in the resource's context). -| (<annotationName>)? | Annotations to be applied to this method. Annotations are any property whose key begins with "(" and ends with ")" and whose name (the part between the beginning and ending parentheses) is a declared annotation name. See section [Annotations](#annotation) for more information. +| (<annotationName>)? | Annotations to be applied to this method. Annotations are any property whose key begins with "(" and ends with ")" and whose name (the part between the beginning and ending parentheses) is a declared annotation name. See section [Annotations](#annotations) for more information. | queryParameters? | Detailed information about any query parameters needed by this method. Mutually exclusive with queryString. | headers? | Detailed information about any request headers needed by this method. | queryString? | Specifies the query string needed by this method. Mutually exclusive with queryParameters. @@ -1695,7 +1715,7 @@ If a query parameter declaration specifies an array type for the value of the qu If a query parameter declaration specifies a non-array type for the value of the query parameter (or doesn't specify a type, which is equivalent to specifying a string type), processors MUST interpret this as disallowing multiple instances of that query parameter in the request. -If a query parameter declaration specifies an object type or a union of non-scalar types for the value of the query parameter, or if it specifies an array type for the value of the query parameter and the underlying type of the array is an object type or union of non-scalar types, then processors MUST default to treating the format of the query parameter value as JSON in applying the type to instances of that query parameter. They MAY allow other treatments based on annotations. +If a query parameter declaration specifies an object type or a union of non-scalar types for the value of the query parameter, or if it specifies an array type for the value of the query parameter and the underlying type of the array is an object type or union of non-scalar types, then processors MUST default to treating the format of the query parameter value as JSON in applying the type to instances of that query parameter. If a query parameter declaration specifies a non-string scalar type or union of non-string scalar types for the value of the query parameter, or if it specifies an array type for the value of the query parameter and the underlying type of the array is a non-string scalar type or union of non-string scalar types, the standard serialization rules for types MUST be invoked in applying the type to instances of that query parameter. From 36a016379fed8ab545a197be397f6f25f88c7ac5 Mon Sep 17 00:00:00 2001 From: Christian Vogel Date: Mon, 7 Mar 2016 11:24:12 +0000 Subject: [PATCH 017/241] Fixed example and replaced discriminator value from person to user. Closes #214 --- versions/raml-10/raml-10.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/versions/raml-10/raml-10.md b/versions/raml-10/raml-10.md index 45535513..a4938693 100644 --- a/versions/raml-10/raml-10.md +++ b/versions/raml-10/raml-10.md @@ -1271,7 +1271,7 @@ types: employeeId: string User: type: Person - discriminatorValue: person + discriminatorValue: user properties: userId: string ``` From ac4f44c6466e72337bf37a0899ca662f7b522d3d Mon Sep 17 00:00:00 2001 From: Christian Vogel Date: Mon, 7 Mar 2016 12:07:23 +0000 Subject: [PATCH 018/241] Clarification about resource types and optional properties does not force to define a custom parameter. Closes #143 --- versions/raml-10/raml-10.md | 10 +++++++--- 1 file changed, 7 insertions(+), 3 deletions(-) diff --git a/versions/raml-10/raml-10.md b/versions/raml-10/raml-10.md index 23473731..b364e989 100644 --- a/versions/raml-10/raml-10.md +++ b/versions/raml-10/raml-10.md @@ -2020,7 +2020,7 @@ When defining resource types and traits, it can be useful to capture patterns th To accommodate this need, a resource type or trait definition MAY append a question mark ("?") suffix to the name of any object-valued property that should not be applied if it doesn't already exist in the resource or method at the corresponding level. A property is considered object-valued if its value is of type object or of a type that has object at the base of its inheritance hierarchy. The question mark suffix indicates that the value of the property in the resource type or trait should be applied if the property name itself (without the question mark) is already defined (whether explicitly or implicitly) at the corresponding level in that resource or method. -The following example shows a resource type called corpResource with an optional post? property that defines a required header called X-Chargeback. If the inheriting resource defines a post method, it will include the X-Chargeback header requirement. If the inheriting resource does not define a post method, one will not be defined for it by dint of inheriting from the corpResource resource type. +The following example shows a resource type called corpResource with an optional post? property that defines a required header called X-Chargeback and also a custom parameter called TextAboutPost. If the inheriting resource defines a post method, it will include the X-Chargeback header requirement and TextAboutPost MUST be defined as well. If the inheriting resource does not define a post method, one will not have to define the X-Chargeback header or forced to define the TextAboutPost parameter by dint of inheriting from the corpResource resource type. ```yaml #%RAML 1.0 @@ -2028,17 +2028,21 @@ title: Example of Optional Properties resourceTypes: - corpResource: post?: + description: Some info about <>. headers: X-Chargeback: required: true /servers: - type: corpResource + type: + corpResource: + TextAboutPost: post method # post defined which will force to define the TextAboutPost parameter get: post: # will require the X-Chargeback header /queues: type: corpResource get: - # will not have a post method defined + # will not have a post method defined which means one MUST not have to define + # the TextAboutPost parameter ``` Note that a question mark can also appear as the last character of a RAML Type property name. If you wish to use this syntax within a Resource Type or Trait you should escape it with a backslash ( "\?"). Consider an example of body type defined inside trait by a properties set: From 412248d33d700154d6b5ad41f11c8eb3f9ae8383 Mon Sep 17 00:00:00 2001 From: Christian Vogel Date: Mon, 7 Mar 2016 12:56:21 +0000 Subject: [PATCH 019/241] clarify collapsing of consecutive slashes due to a trailing slash in the base URI. closes #256. --- versions/raml-10/raml-10.md | 22 ++++++++++++++++++++++ 1 file changed, 22 insertions(+) diff --git a/versions/raml-10/raml-10.md b/versions/raml-10/raml-10.md index 23473731..548ef7c1 100644 --- a/versions/raml-10/raml-10.md +++ b/versions/raml-10/raml-10.md @@ -214,6 +214,28 @@ baseUriParameters: description: The name of the bucket ``` +When the base URI ends in one or more slashes (`/`), those trailing slashes are to be omitted in constructing the absolute paths for the resources using that base URI. + +For example, in + +```yaml +baseUri: http://api.test.com/common/ +/users: + /groups: +``` + +the absolute paths for the two resources are `http://api.test.com/common/users` and `http://api.test.com/common/users/groups`. + +In a more complicated examples with consecutive slashes in multiple places, note that only trailing slashes in the base URI are collapsed: + +```yaml +baseUri: //api.test.com//common// +/: + /users/: + /groups//: +``` +leads to the following 3 resource absolute paths: `//api.test.com//common/`, `//api.test.com//common//users/` and `//api.test.com//common//users//groups//`. + ### Protocols The OPTIONAL **protocols** property specifies the protocols that an API supports. If the protocols property is not explicitly included, the protocol(s) specified at the baseUri property is (are) used; if the protocols property is specified explicitly, it overrides any protocol specified in the baseUri property. The protocols property MUST be a non-empty array of strings, of values HTTP and/or HTTPS, and is case-insensitive. From d4866d4e210645516e40d1fa87510aa03e5d0ca9 Mon Sep 17 00:00:00 2001 From: Christian Vogel Date: Mon, 7 Mar 2016 14:44:48 +0000 Subject: [PATCH 020/241] Add more clarification for Pass Through and what value it's referring to. closes #219 --- versions/raml-10/raml-10.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/versions/raml-10/raml-10.md b/versions/raml-10/raml-10.md index 23473731..45535e64 100644 --- a/versions/raml-10/raml-10.md +++ b/versions/raml-10/raml-10.md @@ -2420,7 +2420,7 @@ securitySchemes: ##### Pass Through -Pass Through authentication does not have any specific settings defined and the implementation is known to RAML. For every header or queryParameter defined in describedBy, the value is required and passed along with the request without modification. The following is an example: +Pass Through authentication does not have any specific settings defined and the implementation is known to RAML. One MUST provide a value for every header or queryParameter defined in describedBy, and passed along with the request without modification. The following is an example: ```yaml #%RAML 1.0 From 3f2aa7af299ccf761c3f0ac4b8a8871485913438 Mon Sep 17 00:00:00 2001 From: Christian Vogel Date: Mon, 7 Mar 2016 16:19:04 +0000 Subject: [PATCH 021/241] changed date type representation according to issue 202 --- versions/raml-10/raml-10.md | 30 +++++++++++++++++++++++++++--- 1 file changed, 27 insertions(+), 3 deletions(-) diff --git a/versions/raml-10/raml-10.md b/versions/raml-10/raml-10.md index 45535e64..71e3ea7d 100644 --- a/versions/raml-10/raml-10.md +++ b/versions/raml-10/raml-10.md @@ -710,12 +710,36 @@ types: ##### Date -As defined in [RFC2616](https://www.ietf.org/rfc/rfc2616.txt), all date/time stamps are represented in Greenwich Mean Time (GMT), which for HTTP is equal to UTC (Coordinated Universal Time). This is indicated by including "GMT" as the three-letter abbreviation for the timezone. Example: `Sun, 06 Nov 1994 08:49:37 GMT` +The following date type representations MUST be supported: + +| Type | Description | +|:-----|:------------| +| date-only | the "full-date" notation of [RFC3339](http://xml2rfc.ietf.org/public/rfc/html/rfc3339.html#anchor14), namely `yyyy-mm-dd` (no implications about time or timezone-offset) +| time-only | the "partial-time" notation of [RFC3339](http://xml2rfc.ietf.org/public/rfc/html/rfc3339.html#anchor14), namely hh:mm:ss\[.ff...\] (no implications about date or timezone-offset) +| datetime-only | combined date-only and time-only with a separator of "T", namely yyyy-mm-ddThh:mm:ss\[.ff...\] (no implications about timezone-offset) +| datetime | a timestamp, either in the "date-time" notation of [RFC3339](http://xml2rfc.ietf.org/public/rfc/html/rfc3339.html#anchor14), if _format_ is omitted or is set to `rfc3339`, or in the format defined in [RFC2616](https://www.ietf.org/rfc/rfc2616.txt), if _format_ is set to `rfc2616` + +The additional property _format_ MUST only be available when the type equals to _datetime_ and the value MUST be either `rfc3339` or `rfc2616`. Any other values are invalid. ```yaml types: - DateOfBirth: - type: date + birthday: + type: date-only # no implications about time or offset + example: 2015-05-23 + lunchtime: + type: time-only # no implications about date or offset + example: 12:30:00 + fireworks: + type: datetime-only # no implications about offset + example: 2015-07-04T21:00:00 + created: + type: datetime + example: 2016-02-28T16:41:41.090Z + format: rfc3339 # the default, so needn't be specified + If-Modified-Since: + type: datetime + example: Sun, 28 Feb 2016 16:41:41 GMT + format: rfc2616 # this time it's required as otherwise the example is in an invalid format ``` ##### File From 46cfbabbcabb1d98b2dc69932ad5416a001bc9f4 Mon Sep 17 00:00:00 2001 From: Christian Vogel Date: Mon, 7 Mar 2016 19:43:08 +0000 Subject: [PATCH 022/241] applied Uri's comments --- versions/raml-10/raml-10.md | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/versions/raml-10/raml-10.md b/versions/raml-10/raml-10.md index 27969293..e46abf1c 100644 --- a/versions/raml-10/raml-10.md +++ b/versions/raml-10/raml-10.md @@ -1950,10 +1950,10 @@ Parameter values MAY further be transformed by applying one of the following fun | !lowercase | The !lowercase function MUST convert the value of the parameter to lowercase letters.

    for example: `userId --> userid` | !lowercamelcase | The !lowercamelcase function MUST convert the value of the parameter to camel case where the first letter is lowercase.

    for example: `userId --> userId` | !uppercamelcase | The !uppercamelcase function MUST convert the value of the parameter to camel case where the first letter is uppercase.

    for example: `userId --> UserId` -| !lowerunderscorecase | The !lowerunderscorecase function MUST convert the value of the parameter to lowercase letters and if the value is a compound word the function MUST add an additional underscore between each word except when there is already one present.

    for example: `userId --> user_id` -| !upperunderscorecase | The !upperunderscorecase function MUST convert the value of the parameter to uppercase letters and if the value is a compound word the function MUST add an additional underscore between each word except when there is already one present.

    for example: `userId --> USER_ID` -| !lowerhyphencase | The !lowerhyphencase function MUST convert the value of the parameter to lowercase letters and if the value is a compound word the function MUST add an additional hyphen between each word except when there is already one present.

    for example: `userId --> user-id` -| !upperhyphencase | The !upperhyphencase function MUST convert the value of the parameter to uppercase letters and if the value is a compound word the function MUST add an additional hyphen between each word except when there is already one present.

    for example: `userId --> USER-ID` +| !lowerunderscorecase | The !lowerunderscorecase function MUST convert the value of the parameter to lowercase letters; if the value is a compound word, the function MUST also add an additional underscore between consecutive words which are not already separated by one or more underscores.

    for example: `userId` --> `user_id` +| !upperunderscorecase | The !upperunderscorecase function MUST convert the value of the parameter to uppercase letters; if the value is a compound word, the function MUST also add an additional underscore between consecutive words which are not already separated by one or more underscores.

    for example: `userId --> USER_ID` +| !lowerhyphencase | The !lowerhyphencase function MUST convert the value of the parameter to lowercase letters; if the value is a compound word, the function MUST also add an additional hyphen between consecutive words which are not already separated by one or more hyphen.

    for example: `userId --> user-id` +| !upperhyphencase | The !upperhyphencase function MUST convert the value of the parameter to uppercase letters; if the value is a compound word, the function MUST also add an additional hyphen between consecutive words which are not already separated by one or more hyphen.

    for example: `userId --> USER-ID` To apply these functions, append them to the parameter name within the double angle brackets, separated from the parameter name with a pipe ("|") character and optional whitespace padding. Here is an example that uses both functions as well as reserved parameters: From 2e9171fab682fcc6df81a7def2c1293e3ce9c130 Mon Sep 17 00:00:00 2001 From: Erik Wilde Date: Tue, 8 Mar 2016 10:25:39 +0000 Subject: [PATCH 023/241] fixing typo "behavior" should be spelled consistently across the spec. --- versions/raml-10/raml-10.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/versions/raml-10/raml-10.md b/versions/raml-10/raml-10.md index 601c0200..4dbf2813 100644 --- a/versions/raml-10/raml-10.md +++ b/versions/raml-10/raml-10.md @@ -626,7 +626,7 @@ types: ### Array Types -Array Types are declared by using the array qualifier at the end of a Type Expression. If you are defining a top-level Array Type ( like the example below ), you can pass the following additional properties to further restrict its behaviour. +Array Types are declared by using the array qualifier at the end of a Type Expression. If you are defining a top-level Array Type ( like the example below ), you can pass the following additional properties to further restrict its behavior. | Property | Description | |:----------|:----------| From d1f8afd0cf4dce01e442683157bcdde29422927a Mon Sep 17 00:00:00 2001 From: Christian Vogel Date: Tue, 8 Mar 2016 10:31:38 +0000 Subject: [PATCH 024/241] Incorporated feedback on previous commit removing stuff not related to the issue 73 --- versions/raml-10/raml-10.md | 8 -------- 1 file changed, 8 deletions(-) diff --git a/versions/raml-10/raml-10.md b/versions/raml-10/raml-10.md index 3ea42d0e..00245a30 100644 --- a/versions/raml-10/raml-10.md +++ b/versions/raml-10/raml-10.md @@ -29,14 +29,6 @@ A **resource** is the conceptual mapping to an entity or set of entities. Optional properties are indicated with trailing question marks (e.g. **description?**). -### Markdown - -Throughout this specification, **Markdown** means [GitHub-Flavored Markdown](https://help.github.com/articles/github-flavored-markdown/). - -### Media Types - -The value of a specific media type property MUST conform to the media type specification in [RFC6838](https://tools.ietf.org/html/rfc6838). - ### Template URI A template URI refers to any URI parameters using curly brackets ({}) to mark a section inside a resource's relative URI as variable element. From 37baf2c4336296998a34f506f8a486a78ce21f86 Mon Sep 17 00:00:00 2001 From: Christian Vogel Date: Tue, 8 Mar 2016 10:38:28 +0000 Subject: [PATCH 025/241] Incorporated feedback on previous commit changing the wording around the optional property parameter being not required --- versions/raml-10/raml-10.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/versions/raml-10/raml-10.md b/versions/raml-10/raml-10.md index b364e989..6f4737b5 100644 --- a/versions/raml-10/raml-10.md +++ b/versions/raml-10/raml-10.md @@ -2020,7 +2020,7 @@ When defining resource types and traits, it can be useful to capture patterns th To accommodate this need, a resource type or trait definition MAY append a question mark ("?") suffix to the name of any object-valued property that should not be applied if it doesn't already exist in the resource or method at the corresponding level. A property is considered object-valued if its value is of type object or of a type that has object at the base of its inheritance hierarchy. The question mark suffix indicates that the value of the property in the resource type or trait should be applied if the property name itself (without the question mark) is already defined (whether explicitly or implicitly) at the corresponding level in that resource or method. -The following example shows a resource type called corpResource with an optional post? property that defines a required header called X-Chargeback and also a custom parameter called TextAboutPost. If the inheriting resource defines a post method, it will include the X-Chargeback header requirement and TextAboutPost MUST be defined as well. If the inheriting resource does not define a post method, one will not have to define the X-Chargeback header or forced to define the TextAboutPost parameter by dint of inheriting from the corpResource resource type. +The following example shows a resource type called corpResource with an optional post? property that defines a required header called X-Chargeback and also a custom parameter called TextAboutPost. If the inheriting resource defines a post method, it will include the X-Chargeback header requirement and TextAboutPost MUST be defined as well. If the inheriting resource does not define a post method, one will not have to define the X-Chargeback header or be forced to define the TextAboutPost parameter by dint of inheriting from the corpResource resource type. ```yaml #%RAML 1.0 @@ -2041,8 +2041,8 @@ resourceTypes: /queues: type: corpResource get: - # will not have a post method defined which means one MUST not have to define - # the TextAboutPost parameter + # will not have a post method defined which means the TextAboutPost parameter is + # not required ``` Note that a question mark can also appear as the last character of a RAML Type property name. If you wish to use this syntax within a Resource Type or Trait you should escape it with a backslash ( "\?"). Consider an example of body type defined inside trait by a properties set: From c89b5c2f268ee8672287a81fd418f5bf3025e346 Mon Sep 17 00:00:00 2001 From: Christian Vogel Date: Tue, 8 Mar 2016 10:40:08 +0000 Subject: [PATCH 026/241] made it more clear that the X-Chargeback header is also not required if post is not defined --- versions/raml-10/raml-10.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/versions/raml-10/raml-10.md b/versions/raml-10/raml-10.md index 6f4737b5..8f343ac9 100644 --- a/versions/raml-10/raml-10.md +++ b/versions/raml-10/raml-10.md @@ -2042,7 +2042,7 @@ resourceTypes: type: corpResource get: # will not have a post method defined which means the TextAboutPost parameter is - # not required + # not required; same for the X-Chargeback header ``` Note that a question mark can also appear as the last character of a RAML Type property name. If you wish to use this syntax within a Resource Type or Trait you should escape it with a backslash ( "\?"). Consider an example of body type defined inside trait by a properties set: From 0e9b3f907375a798a9f1c55b89a5865875e5c700 Mon Sep 17 00:00:00 2001 From: Christian Vogel Date: Tue, 8 Mar 2016 11:39:11 +0000 Subject: [PATCH 027/241] add support for multiple default media types --- versions/raml-10/raml-10.md | 31 ++++++++++++++++++++++++------- 1 file changed, 24 insertions(+), 7 deletions(-) diff --git a/versions/raml-10/raml-10.md b/versions/raml-10/raml-10.md index 733255de..05f8018f 100644 --- a/versions/raml-10/raml-10.md +++ b/versions/raml-10/raml-10.md @@ -260,19 +260,36 @@ baseUri: https://na1.salesforce.com/services/data/{version}/chatter The media types expected from API requests that contain a body, and returned by API responses, can be defaulted by specifying the OPTIONAL **mediaType** property, so they do not need to be specified within every body definition. -The value of the mediaType property MUST be a media type string conforming to the media type specification in [RFC6838](https://tools.ietf.org/html/rfc6838). +The value of the mediaType property MUST be a sequence of media type strings conforming to the media type specification in [RFC6838](https://tools.ietf.org/html/rfc6838); with the premise that all of them are described by exactly the same types and/or examples. -This example shows a RAML snippet for an API that accepts and returns JSON-formatted bodies. If the remainder of this API's specification doesn't explicitly specify another media type, this API only accepts and returns JSON-formatted bodies. +This example shows a RAML snippet for an API that accepts and returns JSON- and XML-formatted bodies. If the remainder of this API's specification doesn't explicitly specify another media type, this API only accepts and returns JSON- and XML-formatted bodies. ```yaml #%RAML 1.0 -title: Stormpath REST API -version: v1 -baseUri: https://api.stormpath.com/{version} -mediaType: application/json +title: New API +mediaType: [ application/json, application/xml ] ``` -The default media type can be overridden by defining a `mediaType` node explicitly to a [body](#bodies) of an API request or response. +The default media type can be overridden by defining a `mediaType` node explicitly to a [body](#bodies) of an API request or response. When one defines a root-level `mediaType` and then override that in a body by defining explicitly a media type node, none of the root level media types apply to that node, other than the media types explicitly defined within that node. The example below shows a RAML snippet that illustrates that behavior. The resource `/list` returns a `Person[]` body represented as either JSON or XML. On the other hand, the resource `/send` overrides the default media types with an explicit definition of an `application/json` node and therefore only accepts a JSON-formatted body. + +```yaml +#%RAML 1.0 +title: New API +mediaType: [ application/json, application/xml ] +types: + Person: + Another: +/list: + get: + responses: + 200: + body: Person[] +/send: + post: + body: + application/json: + type: Another +``` ### Default Security From 1401841414cc4031800dbfe32ed20a7d8748b939 Mon Sep 17 00:00:00 2001 From: Christian Vogel Date: Tue, 8 Mar 2016 12:30:41 +0000 Subject: [PATCH 028/241] added new chapter that illustrates how one annotates scalar-value nodes and the available scalar-value nodes, and also added Scalar to the annotation target table --- versions/raml-10/raml-10.md | 67 +++++++++++++++++++++++++++++++++++++ 1 file changed, 67 insertions(+) diff --git a/versions/raml-10/raml-10.md b/versions/raml-10/raml-10.md index 733255de..a222cefe 100644 --- a/versions/raml-10/raml-10.md +++ b/versions/raml-10/raml-10.md @@ -2682,6 +2682,72 @@ annotationTypes: (testHarness): usersTest ``` +#### Annotating Scalar-valued Nodes + +It is often useful to annotate scalar-valued nodes, e.g. `baseUri`. Since annotations are applied as extra key-value pairs to nodes that accept key-value pairs already (i.e. map-valued nodes), they cannot be easily applied to scalar-valued nodes. To apply annotations to any scalar-valued node, a RAML processor MUST also support scalar-valued nodes to be expressed as a map, with the single allowed key `value`, as an alternative to the normal syntax. + +The example below shows a scalar-valued node which is normally expressed as: + +```yaml +baseUri: http://www.example.com/api +``` + +and the alternative map syntax, with `value` as key: + +```yaml +baseUri: + value: http://www.example.com/api +``` + +and then annotations may be applied as usual, e.g.: + +```yaml +baseUri: + value: http://www.example.com/api + (redirectable): true +``` + +The following is a list of all available scalar-valued nodes supported in RAML: + +``` +displayName +description +type +schema +default +example +usage +repeat +required +content +strict +minLength +maxLength +uniqueItems +minItems +maxItems +discriminator +minProperties +maxProperties +discriminatorValue +pattern +format +minimum +maximum +multipleOf +requestTokenUri +authorizationUri +tokenCredentialsUri +accessTokenUri +title +version +baseUri +mediaType +extends +``` + +#### Annotation Targets + The location within an API specification where annotations may be applied MUST be one of the target locations in the following Target Locations table. The targets are the locations themselves, not sub-properties within the locations; for example, the Method target refers to the method property and not to the method's display name, description, etc. @@ -2696,6 +2762,7 @@ The location within an API specification where annotations may be applied MUST b | RequestBody | The body property of a method | ResponseBody | The body property of a response | TypeDeclaration | A data type declaration (inline or in a global types collection), header declaration, query parameter declaration, or URI parameter declaration, or property within any of these declarations, where the type property may be used. +| Scalar | A scalar-valued node listed in [Annotating Scalar-valued Nodes](#scalar-valued-nodes). | NamedExample | A property of the examples property, whose key is a name of an example and whose value describes the example. | ResourceType | A resource type property | Trait | A trait property From e47ae50cfc721fa6bb6d83556eff6ea6b5cef26b Mon Sep 17 00:00:00 2001 From: Christian Vogel Date: Wed, 9 Mar 2016 14:52:24 +0000 Subject: [PATCH 029/241] added message that highlights what language each function that you can apply to resource type parameters is supported by RAML --- versions/raml-10/raml-10.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/versions/raml-10/raml-10.md b/versions/raml-10/raml-10.md index 733255de..499f87d0 100644 --- a/versions/raml-10/raml-10.md +++ b/versions/raml-10/raml-10.md @@ -2012,12 +2012,12 @@ In trait declarations, there is an additional reserved parameter named **methodN The processing application MUST set the value of the methodName parameter to the inheriting method's name. -Parameter values MAY further be transformed by applying one of the following functions. +Parameter values MAY further be transformed by applying one of the following functions. The only locale supported by this version of RAML is United States English. | Function | Definition | |:---------|:-----------| -| !singularize | The !singularize function MUST act on the value of the parameter by a locale-specific singularization of its original value. The only locale supported by this version of RAML is United States English.

    for example: `users --> user` -| !pluralize | The !pluralize function MUST act on the value of the parameter by a locale-specific pluralization of its original value. The only locale supported by this version of RAML is United States English.

    for example: `user --> users` +| !singularize | The !singularize function MUST act on the value of the parameter by a locale-specific singularization of its original value.

    for example: `users --> user` +| !pluralize | The !pluralize function MUST act on the value of the parameter by a locale-specific pluralization of its original value.

    for example: `user --> users` | !uppercase | The !uppercase function MUST convert the value of the parameter to uppercase letters.

    for example: `userId --> USERID` | !lowercase | The !lowercase function MUST convert the value of the parameter to lowercase letters.

    for example: `userId --> userid` | !lowercamelcase | The !lowercamelcase function MUST convert the value of the parameter to camel case where the first letter is lowercase.

    for example: `userId --> userId` From da03e141377606f9db71d37df0da77d7db9b8b2e Mon Sep 17 00:00:00 2001 From: Christian Vogel Date: Thu, 10 Mar 2016 11:51:03 +0000 Subject: [PATCH 030/241] reviewed text adn changed language to reflect that RAML supports a sequence of media types instead of a single. also changed the root-level key name from mediaType to mediaTypes. --- versions/raml-10/raml-10.md | 34 +++++++++++++++++----------------- 1 file changed, 17 insertions(+), 17 deletions(-) diff --git a/versions/raml-10/raml-10.md b/versions/raml-10/raml-10.md index 05f8018f..b18651bc 100644 --- a/versions/raml-10/raml-10.md +++ b/versions/raml-10/raml-10.md @@ -105,7 +105,7 @@ This example shows a small part of a RAML API definition for the GitHub v3 publi title: GitHub API version: v3 baseUri: https://api.github.com -mediaType: application/json +mediaTypes: [ application/json ] securitySchemes: - oauth_2_0: !include securitySchemes/oauth_2_0.raml types: @@ -139,7 +139,7 @@ The following table enumerates the possible properties at the root of a RAML doc | baseUri? | A URI that's to be used as the base of all the resources' URIs. Often used as the base of the URL of each resource, containing the location of the API. Can be a [template URI](#template-uri). See section [Base URI and Base URI Parameters](#base-uri-and-base-uri-parameters) for more information. | baseUriParameters? | Named parameters used in the baseUri (template). See section [Base URI and Base URI Parameters](#base-uri-and-base-uri-parameters) for more information. | protocols? | The protocols supported by the API. The protocols property MUST contain one or more of the supported protocols: "HTTP", "HTTPS". (case-insensitive). -| mediaType? | The default media type to use for request and response bodies (payloads), e.g. "application/json" +| mediaTypes? | Default media types to use for request and response bodies (payloads), e.g. "application/json" | securedBy? | The security schemes that apply to every resource and method in the API. See section [Applying Security Schemes](#applying-security-schemes) for more information. | /<relativeUri>? | The resources of the API, identified as relative URIs that begin with a slash (/). Every property whose key begins with a slash (/), and is either at the root of the API definition or is the child property of a resource property, is a resource property, e.g.: /users, /{groupId}, etc. | documentation? | Additional overall documentation for the API. See section [User Documentation](#user-documentation) for more information. @@ -256,26 +256,26 @@ protocols: [ HTTP, HTTPS ] baseUri: https://na1.salesforce.com/services/data/{version}/chatter ``` -### Default Media Type +### Default Media Types -The media types expected from API requests that contain a body, and returned by API responses, can be defaulted by specifying the OPTIONAL **mediaType** property, so they do not need to be specified within every body definition. +The media types expected from API requests that contain a body, and returned by API responses, can be defaulted by specifying the OPTIONAL **mediaTypes** property, so they do not need to be specified within every body definition. -The value of the mediaType property MUST be a sequence of media type strings conforming to the media type specification in [RFC6838](https://tools.ietf.org/html/rfc6838); with the premise that all of them are described by exactly the same types and/or examples. +The value of the mediaTypes property MUST be a sequence of media type strings conforming to the media type specification in [RFC6838](https://tools.ietf.org/html/rfc6838); with the premise that all of them are described by exactly the same types and/or examples. This example shows a RAML snippet for an API that accepts and returns JSON- and XML-formatted bodies. If the remainder of this API's specification doesn't explicitly specify another media type, this API only accepts and returns JSON- and XML-formatted bodies. ```yaml #%RAML 1.0 title: New API -mediaType: [ application/json, application/xml ] +mediaTypes: [ application/json, application/xml ] ``` -The default media type can be overridden by defining a `mediaType` node explicitly to a [body](#bodies) of an API request or response. When one defines a root-level `mediaType` and then override that in a body by defining explicitly a media type node, none of the root level media types apply to that node, other than the media types explicitly defined within that node. The example below shows a RAML snippet that illustrates that behavior. The resource `/list` returns a `Person[]` body represented as either JSON or XML. On the other hand, the resource `/send` overrides the default media types with an explicit definition of an `application/json` node and therefore only accepts a JSON-formatted body. +Default media types can be overridden by defining a `mediaType` node explicitly to a [body](#bodies) of an API request or response. When one defines a root-level `mediaTypes` node and then override that in a body by defining explicitly another or the same media type node, none of the root level media types apply to that node, other than the media types explicitly defined within that node. The example below shows a RAML snippet that illustrates that behavior. The resource `/list` returns a `Person[]` body represented as either JSON or XML. On the other hand, the resource `/send` overrides the default media types with an explicit definition of an `application/json` node and therefore only accepts a JSON-formatted body. ```yaml #%RAML 1.0 title: New API -mediaType: [ application/json, application/xml ] +mediaTypes: [ application/json, application/xml ] types: Person: Another: @@ -348,7 +348,7 @@ succinct than JSON and XML schemas while retaining their flexibility and express ```yaml #%RAML 1.0 title: My API with Types -mediaType: application/json +mediaTypes: [ application/json ] types: Org: type: object @@ -1836,7 +1836,7 @@ baseUri: https://api.twitter.com/{version} The HTTP request **body** for a method is specified using the OPTIONAL body property. For example, to create a resource using a POST or PUT, the body of the request would usually include the details of the resource to be created. -The value of the body property is termed a **body declaration**. The body declaration is an object whose property names are the valid media types of the request body and whose property values are the corresponding data type declaration or data type name describing the request body. If a [default media type](#default-media-type) has been declared at the root of the API via the mediaType property, then the body declaration may alternatively be directly the data type declaration or data type name describing the request body for that media type. +The value of the body property is termed a **body declaration**. The body declaration is an object whose property names are the valid media types of the request body and whose property values are the corresponding data type declaration or data type name describing the request body. If [default media types](#default-media-type) has been declared at the root of the API, then the body declaration may alternatively be directly the data type declaration or data type name describing the request body for that media type. In the first case above, when the property names represent media types, each property name MUST be a media type string conforming to the media type specification in [RFC6838](#https://tools.ietf.org/html/rfc6838). @@ -1845,7 +1845,7 @@ The following example illustrates various combinations of both default and non-d ```yaml #%RAML 1.0 title: Example of request bodies -mediaType: application/json +mediaTypes: [ application/json ] types: User: properties: @@ -1892,7 +1892,7 @@ The following example illustrates some possible responses. ```yaml #%RAML 1.0 title: Example with responses -mediaType: application/json +mediaTypes: [ application/json ] types: Invoice: properties: @@ -2050,7 +2050,7 @@ To apply these functions, append them to the parameter name within the double an #%RAML 1.0 title: Example API version: v1 -mediaType: application/json +mediaTypes: [ application/json ] types: Users: !include types/users.raml User: !include types/user.raml @@ -2612,7 +2612,7 @@ The following is an example of various annotation type declarations and the appl ```yaml #%RAML 1.0 title: Illustrating annotations -mediaType: application/json +mediaTypes: [ application/json ] annotationTypes: experimental: feedbackRequested: @@ -2679,7 +2679,7 @@ The example below, a small subset of the previous example, shows an explicit dec ```yaml #%RAML 1.0 title: Testing annotations -mediaType: application/json +mediaTypes: [ application/json ] annotationTypes: testHarness: type: string @@ -2692,7 +2692,7 @@ The following is semantically equivalent but relies on the implicit default decl ```yaml #%RAML 1.0 title: Testing annotations -mediaType: application/json +mediaTypes: [ application/json ] annotationTypes: testHarness: /users: @@ -2728,7 +2728,7 @@ The following example illustrates applying some restrictions on the allowed targ ```yaml #%RAML 1.0 title: Illustrating allowed targets -mediaType: application/json +mediaTypes: [ application/json ] annotationTypes: meta-resource-method: allowedTargets: [ Resource, Method ] From 8d9c184033075a3ce57f492862dcccac515c862f Mon Sep 17 00:00:00 2001 From: Christian Vogel Date: Thu, 10 Mar 2016 13:08:50 +0000 Subject: [PATCH 031/241] removed all occurrences for 'allowMultiple' from the specification --- versions/raml-10/raml-10.md | 7 +------ 1 file changed, 1 insertion(+), 6 deletions(-) diff --git a/versions/raml-10/raml-10.md b/versions/raml-10/raml-10.md index 7ef9c0e7..1661c36f 100644 --- a/versions/raml-10/raml-10.md +++ b/versions/raml-10/raml-10.md @@ -2602,8 +2602,6 @@ annotationTypes: testHarness: type: string # This line may be omitted as it's the default type badge: # This annotation type, too, allows string values - assertion: - allowMultiple: true clearanceLevel: properties: level: @@ -2626,22 +2624,19 @@ annotationTypes: (feedbackRequested): responses: 200: - (assertion): Condition 1 - (assertion): Condition 2 ``` Annotations applied to a data type are not inherited when that data type is inherited. However, processors SHOULD make the information about the annotations in the data type hierarchy available. Annotations applied to, or applied within, a resource type or trait are also applied to the resource type or resource or method that inherits it. In particular, if a trait is applied to a resource type or resource, all annotations on or within that trait are applied implicitly to all methods of that resource. If the inheriting resource type or resource or method directly (explicitly) apply an annotation of a given type, then this annotation overrides all applications of that annotation type which would otherwise have been inherited and implicitly applied. In particular, if a trait is applied to a resource type or resource, and the resource type or resource apply an annotation of some type, then any and all applications of annotations of that type to that trait are overridden. ### Declaring Annotation Types -Annotation types are declared using the OPTIONAL root-level **annotationTypes** property. The value of the annotationsType property is an object whose keys define annotation type names, also referred to as annotations, and whose values are objects called annotation type declarations. An annotation type declaration has the same syntax as a data type declaration, and its facets have the same syntax as the corresponding ones for data types, but with the addition of 2 facets: allowMultiple and allowedTargets. Just as a data type declaration constrains the value of a URI parameter, query parameter, header, or body of that type, so an annotation type declaration constrains the value of an annotation of that type. The allowMultiple facet determines whether the annotation may be applied multiple times at the same location, while the allowedTargets facet restricts at which kinds of locations the annotation may be applied. Annotation types, like data types, may extend other data types, but annotation types may not themselves be extended nor used anywhere data types may be used. +Annotation types are declared using the OPTIONAL root-level **annotationTypes** property. The value of the annotationsType property is an object whose keys define annotation type names, also referred to as annotations, and whose values are objects called annotation type declarations. An annotation type declaration has the same syntax as a data type declaration, and its facets have the same syntax as the corresponding ones for data types, but with the addition of the allowedTargets facet. Just as a data type declaration constrains the value of a URI parameter, query parameter, header, or body of that type, so an annotation type declaration constrains the value of an annotation of that type. The allowedTargets facet restricts at which kinds of locations the annotation may be applied. Annotation types, like data types, may extend other data types, but annotation types may not themselves be extended nor used anywhere data types may be used. |Property |Description | |:--------|:------------| | displayName? | The displayName attribute specifies the $self's display name. It is a friendly name used only for display or documentation purposes. If displayName is not specified, it defaults to the element's key (the name of the property itself). | description? | The description attribute describes the intended use or meaning of an annotation. This value MAY be formatted using markdown. | (<annotationName>)? | Annotations to be applied to this annotation type. Annotations are any property whose key begins with “(“ and ends with “)” and whose name (the part between the beginning and ending parentheses) is a declared annotation name. See section [Annotations](#annotations) for more information. -| allowMultiple? | Whether multiple instances of annotations of this type may be applied simultaneously at the same location. | allowedTargets? | Restrictions on where annotations of this type can be applied. If this property is specified, annotations of this type may only be applied on a property corresponding to one of the target names specified as the value of this property. Value MUST be one or more of the options described in table [Annotation Target Location](#annotation-target-location). If an annotation type declaration specifies neither a type facet nor a properties facet, then it defaults to a type of string. From 8e1196d272d703862bafefb66a6104f0cf074151 Mon Sep 17 00:00:00 2001 From: Christian Vogel Date: Fri, 11 Mar 2016 14:25:13 +0000 Subject: [PATCH 032/241] changed / from required to optional in chapter Resources and Nested Resources --- versions/raml-10/raml-10.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/versions/raml-10/raml-10.md b/versions/raml-10/raml-10.md index 7ef9c0e7..b1b75ea0 100644 --- a/versions/raml-10/raml-10.md +++ b/versions/raml-10/raml-10.md @@ -1522,7 +1522,7 @@ The value of a resource property is an object whose properties are described in | type? | The resource type which this resource inherits. See section [Applying Resource Types and Traits](#applying-resource-types-and-traits) for more information. | securedBy? | The security schemes that apply to all methods declared (implicitly or explicitly) for this resource. See section [Applying Security Schemes](#applying-security-schemes) for more information. | uriParameters? | Detailed information about any URI parameters of this resource -| /<relativeUri> | A nested resource is identified as any property whose name begins with a slash ("/") and is therefore treated as a relative URI. +| /<relativeUri>? | A nested resource is identified as any property whose name begins with a slash ("/") and is therefore treated as a relative URI. ### Resource Display Name From d0e66278923692e29a9b172df883ed232cb02a16 Mon Sep 17 00:00:00 2001 From: Christian Vogel Date: Fri, 11 Mar 2016 14:31:08 +0000 Subject: [PATCH 033/241] removed the 'parameters' key from any trait or resource type node --- versions/raml-10/raml-10.md | 1 - 1 file changed, 1 deletion(-) diff --git a/versions/raml-10/raml-10.md b/versions/raml-10/raml-10.md index b1b75ea0..ab45e0f5 100644 --- a/versions/raml-10/raml-10.md +++ b/versions/raml-10/raml-10.md @@ -1940,7 +1940,6 @@ Resource type and trait declarations can have the following properties, in addit |:---------|:-----------| | usage? | Instructions on how and when to use this resource type in a RAML spec | uses? | You may import library locally here it contents is accessible only inside of this trait -| parameters? | Optional declaration of the parameters that the resource type employs. The following example illustrates the declaration of several resource types and traits. From 4db42e177929ed32b832659a4aa45c2fd7763d8f Mon Sep 17 00:00:00 2001 From: Christian Vogel Date: Fri, 11 Mar 2016 15:52:55 +0000 Subject: [PATCH 034/241] removed the sequence syntax from the examples node and changed it to represent a map; as well as the syntax of a single example --- versions/raml-10/raml-10.md | 79 +++++++++++++++++++++++-------------- 1 file changed, 49 insertions(+), 30 deletions(-) diff --git a/versions/raml-10/raml-10.md b/versions/raml-10/raml-10.md index ab45e0f5..a56145de 100644 --- a/versions/raml-10/raml-10.md +++ b/versions/raml-10/raml-10.md @@ -415,7 +415,7 @@ declarations may have; certain type declarations may have other properties. | schema? | Alias for the equivalent "type" property, for compatibility with RAML 0.8. Deprecated - API definitions should use the "type" property, as the "schema" alias for that property name may be removed in a future RAML version. The "type" property allows for XML and JSON schemas. | type? | A base type which the current type extends, or more generally a type expression. | example? | An example of an instance of this type. This can be used, e.g., by documentation generators to generate sample values for an object of this type. The `example` property MUST not be available when the `examples` property is already defined. -| examples? | An object containing named examples of instances of this type. This can be used, e.g., by documentation generators to generate sample values for an object of this type. The `examples` property MUST not be available when the `example` property is already defined. See section [Examples](#examples) for more information. +| examples? | An object containing named examples of instances of this type. This can be used, e.g., by documentation generators to generate sample values for an object of this type. The `examples` property MUST not be available when the `example` property is already defined. See section [Examples](#defining-examples-in-raml) for more information. | displayName? | An alternate, human-friendly name for the type | description? | A longer, human-friendly description of the type | (<annotationName>)? | Annotations to be applied to this type. Annotations are any property whose key begins with "(" and ends with ")" and whose name (the part between the beginning and ending parentheses) is a declared annotation name. See section on [Annotations](#annotations) for more information. @@ -1362,28 +1362,59 @@ types: discriminator: true ``` -### Examples +### Defining Examples in RAML -It is highly RECOMMENDED that API documentation include a rich selection of examples. +It is highly RECOMMENDED that API documentation include a rich selection of examples. RAML supports either the definition of multiple examples or a single one for any given instance of a type declaration. -The OPTIONAL **example** property may be used to attach an example of a type's instance to the type declaration. Its value is an instance of the type. +#### Multiple Examples -The OPTIONAL **examples** property may be used to attach multiple examples. Its value can be +The OPTIONAL **examples** property may be used to attach multiple examples to a type declaration. Its value is a map of key-value pairs, where each key represent a unique identifier for an example and the value is a [single example](#single-example) property. -1. an object whose property names are to be interpreted as names of examples, and whose values are objects that describe each example -2. an array of objects that describe each example +The following is an example of the value of an **examples** property: -Each example object has the following properties: +```yaml +message: # {key} - unique id + title: Attention needed + content: You have been added to group 274 +record: # {key} - unique id + name: log item + value: permission check +``` + +#### Single Example + +The OPTIONAL **example** property may be used to attach an example of a type's instance to the type declaration. There are two different ways to represents its value. + +##### The value is a explicit description of a specific type instance + +For example: + +```yaml +title: Attention needed +content: You have been added to group 274 +``` + +##### The value is a map that contains the following additional facets |Property | Description | |:--------|:------------| -| displayName? | An alternate, human-friendly name for the example -| description? | A longer, human-friendly description of the example +| displayName? | An alternate, human-friendly name for the example. If the example is part of an examples node, the default value is the unique identifier that is defined for this example. +| description? | A longer, human-friendly description of the example. | (<annotationName>)? | Annotations to be applied to this example. Annotations are any property whose key begins with "(" and ends with ")" and whose name (the part between the beginning and ending parentheses) is a declared annotation name. See section [Annotations](#annotations) for more information. -| content | The example itself -| strict? | By default, examples are validated against any type declaration. Set this to false to allow examples that need not validate. +| value | The actual example of a type instance. +| strict? | By default, an example is validated against any type declaration. Set this to false avoid that. + +For example: -The example and examples properties are mutually-exclusive in any given type declaration. +```yaml +(pii): true +strict: false +value: + title: Attention needed + content: You have been added to group 274 +``` + +#### Example on how to define example/examples in RAML The following illustrates usage of both example and examples properties. @@ -1404,29 +1435,17 @@ types: properties: name: string address?: string - examples: - - content: - name: Acme - - content: - name: Software Corp - address: 35 Central Street - Org_alt: - type: object - properties: - name: string - address?: string + value? : string examples: acme: - content: - name: Acme + name: Acme softwareCorp: - content: + value: # validate against the available facets for the map value of an example name: Software Corp address: 35 Central Street + value: Gold # validate against instance of the `value` property ``` -RAML Type declarations with examples - ### Using Types in RAML * Types may be used in several positions: @@ -2842,7 +2861,7 @@ A file to be included MAY begin with a RAML fragment identifier line, which cons |:--------|:------------| | DocumentationItem | An item in the collection of items that is the value of the root-level documentation property; see the section on [User Documentation](#user-documentation). | DataType | A data type declaration, where the type property may be used; see the section on [Types](#types) -| NamedExample | A property of the examples property, whose key is a name of an example and whose value describes the example; see the section on [Examples](#examples) +| NamedExample | A property of the examples property, whose key is a name of an example and whose value describes the example; see the section on [Examples](#defining-examples-in-raml) | ResourceType | A single resource type declaration; see the section on [Resource Types and Traits](#resource-types-and-traits) | Trait | A single trait declaration; see the section on [Resource Types and Traits](#resource-types-and-traits) | AnnotationTypeDeclaration | A single annotation type declaration; see the section on [Annotations](#annotations) From f96428c85ebbdcde8a84375337c2a2f2719428df Mon Sep 17 00:00:00 2001 From: Christian Vogel Date: Fri, 11 Mar 2016 16:31:31 +0000 Subject: [PATCH 035/241] change 'uses' to act like 'requires' and that 'uses' is available in ALL RAML Fragments --- versions/raml-10/raml-10.md | 32 +++++++++++++++++--------------- 1 file changed, 17 insertions(+), 15 deletions(-) diff --git a/versions/raml-10/raml-10.md b/versions/raml-10/raml-10.md index ab45e0f5..491b9123 100644 --- a/versions/raml-10/raml-10.md +++ b/versions/raml-10/raml-10.md @@ -3041,9 +3041,11 @@ resourceTypes: #### Applying Libraries -Any number of libraries may be applied by using the OPTIONAL **uses** property. The value of the uses property is an object whose property names are treated as library names and whose property values are libraries, usually included from an external RAML library fragment document. +Any number of libraries may be applied by using the OPTIONAL **uses** property which may ONLY be used at the root of a RAML file (either a root ["master"] RAML file or a RAML fragment file). The value of the uses property is a map of key-value pairs where its keys are treated as library names, or namespaces, and the value MUST be the location of a RAML library file, usually an external RAML library fragment document. -When a library is applied, the data types, resource types, traits, security schemes, and annotation types which it declared are made available in the document in which it was applied, but are referenced via names formed by concatenating the library name followed by a period (".") followed by the name of the data type, resource type, trait, security scheme, or annotation type. In this way the library name defines a namespace for the library's objects within the context in which the library was applied. Libraries may be applied in RAML fragment documents such as trait and resource type fragment documents to make such documents more standalone by including their dependencies. +When a library is applied, the data types, resource types, traits, security schemes, and annotation types which it declared are made available in the document in which it was applied, but are referenced via names formed by concatenating the library name followed by a period (".") followed by the name of the data type, resource type, trait, security scheme, or annotation type. In this way the library name defines a namespace for the library's objects within the context in which the library was applied. That means, namespaces defined in a **uses** statement in a specific file are only consumable within that file, i.e. they are only used to disambiguate the included libraries from each other within that file. Therefore, any processor MUST not be permitted to allow any composition of namespaces using "." across multiple libraries. + +Using **uses** does NOT automatically import the remote library's assets into the local file, but it allows the local file to import those assets by referring to them in its contents: e.g., a RAML type fragment file that uses a library of remote types can then import one of those types by referring to it, and that remote type will be included as if it were defined locally within the RAML type fragment file. The following examples demonstrate the use of a library in a second library, and the use of that second library in a resource type fragment as well as in RAML API definition. @@ -3064,7 +3066,7 @@ types: usage: | Use to define some basic file-related constructs. uses: - file-type: !include libraries/file-type.raml + file-type: libraries/file-type.raml traits: drm: headers: @@ -3081,7 +3083,18 @@ resourceTypes: #%RAML 1.0 ResourceType # This file is located at files-resource.raml uses: - files: !include libraries/files.raml + files: libraries/files.raml +get: + is: files.drm +``` + +The following example is not valid according to the restriction that chaining namespaces is not allowed. + +```yaml +#%RAML 1.0 ResourceType +# Invalid RAML Fragment +uses: + files: libraries/files.raml get: is: files.drm responses: @@ -3091,17 +3104,6 @@ get: type: files.file-type.File ``` -```yaml -#%RAML 1.0 -title: Files API -uses: - files: !include libraries/files.raml -resourceTypes: - file: !include files-resource.raml -/files: - type: file -``` - ### Overlays and Extensions API definitions may need to be extended in a variety of ways for different needs. Annotations allow for adding metadata beyond that which is standardized in this RAML specification. Another set of needs is satisfied by overlaying standard or non-standard metadata on top of an existing API definition without changing its behavior, for example to specify implementation details or provide a translation of human-oriented documentation into different languages. Yet another set of needs requires extending an API definition by adding to its behavior or overriding certain aspects. RAML provides two mechanisms for doing so: overlays and extensions. From 371d81a852913886d397d457fc1bd6a6d5e59fab Mon Sep 17 00:00:00 2001 From: David Date: Sat, 12 Mar 2016 20:52:43 +1100 Subject: [PATCH 036/241] Fix `describedBy` anchor --- versions/raml-10/raml-10.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/versions/raml-10/raml-10.md b/versions/raml-10/raml-10.md index ab45e0f5..202a7170 100644 --- a/versions/raml-10/raml-10.md +++ b/versions/raml-10/raml-10.md @@ -2288,7 +2288,7 @@ Security scheme is declared as follows: | type | The security schemes property MUST be used to specify an API's security mechanisms, including the required settings and the authentication methods that the API supports. one authentication method is allowed if the API supports them. The value MUST be one of the following: OAuth 1.0, OAuth 2.0, Basic Authentication, Digest Authentication, Pass Through, x-<other> | displayName? | An alternate, human-friendly name for the security scheme. | description? | The description MAY be used to describe a security scheme. -| describedBy? | A description of the request components related to Security that are determined by the scheme: the headers, query parameters or responses. As a best practice, even for standard security schemes, API designers SHOULD describe these properties of security schemes. Including the security scheme description completes an API documentation. See explanation about [describedBy](#describedBy) for more information. +| describedBy? | A description of the request components related to Security that are determined by the scheme: the headers, query parameters or responses. As a best practice, even for standard security schemes, API designers SHOULD describe these properties of security schemes. Including the security scheme description completes an API documentation. See explanation about [describedBy](#describedby) for more information. | settings? | The settings attribute MAY be used to provide security scheme-specific information. The required attributes vary depending on the type of security scheme is being declared. It describes the minimum set of properties which any processing application MUST provide and validate if it chooses to implement the security scheme. Processing applications MAY choose to recognize other properties for things such as token lifetime, preferred cryptographic algorithms, and more. See explanation about [settings](#settings) for more information. An optional **securitySchemes** property is defined for RAML document root. From 7c1b86db80b198df56b5660d12eb0d0effdd3cae Mon Sep 17 00:00:00 2001 From: elgris Date: Mon, 14 Mar 2016 15:00:17 +0700 Subject: [PATCH 037/241] Update raml-10.md --- versions/raml-10/raml-10.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/versions/raml-10/raml-10.md b/versions/raml-10/raml-10.md index 9f362570..9480b7dc 100644 --- a/versions/raml-10/raml-10.md +++ b/versions/raml-10/raml-10.md @@ -120,7 +120,7 @@ The following table enumerates the possible properties at the root of a RAML doc | Property | Description | |:----------|:----------| | description? | A longer, human-friendly description of the API -| (<annotationName>)? | Annotations to be applied to this API. Annotations are any property whose key begins with "(" and ends with ")" and whose name (the part between the beginning and ending parentheses) is a declared annotation name. See section [Annotations](#annotation) for more information. +| (<annotationName>)? | Annotations to be applied to this API. Annotations are any property whose key begins with "(" and ends with ")" and whose name (the part between the beginning and ending parentheses) is a declared annotation name. See section [Annotations](#annotations) for more information. | schemas? | Alias for the equivalent "types" property, for compatibility with RAML 0.8. Deprecated - API definitions should use the "types" property, as the "schemas" alias for that property name may be removed in a future RAML version. The "types" property allows for XML and JSON schemas. | types? | Declarations of (data) types for use within this API. See section [RAML Data Types](#raml-data-types) for more information. | traits? | Declarations of traits for use within this API. See section [Resource Types and Traits](#resource-types-and-traits) for more information. @@ -1567,7 +1567,7 @@ In a RESTful API, methods are operations that are performed on a resource. The O |:--------|:------------| | displayName? | An alternate, human-friendly name for the method (in the resource's context). | description? | A longer, human-friendly description of the method (in the resource's context). -| (<annotationName>)? | Annotations to be applied to this method. Annotations are any property whose key begins with "(" and ends with ")" and whose name (the part between the beginning and ending parentheses) is a declared annotation name. See section [Annotations](#annotation) for more information. +| (<annotationName>)? | Annotations to be applied to this method. Annotations are any property whose key begins with "(" and ends with ")" and whose name (the part between the beginning and ending parentheses) is a declared annotation name. See section [Annotations](#annotations) for more information. | queryParameters? | Detailed information about any query parameters needed by this method. Mutually exclusive with queryString. | headers? | Detailed information about any request headers needed by this method. | queryString? | Specifies the query string needed by this method. Mutually exclusive with queryParameters. From a7ddd1045a0f7c2b19707d347663a046200f631d Mon Sep 17 00:00:00 2001 From: Christian Vogel Date: Mon, 14 Mar 2016 12:29:19 +0000 Subject: [PATCH 038/241] restrict optional properties to methods only to close issue 292 --- versions/raml-10/raml-10.md | 30 ++++-------------------------- 1 file changed, 4 insertions(+), 26 deletions(-) diff --git a/versions/raml-10/raml-10.md b/versions/raml-10/raml-10.md index 202a7170..4ade19bd 100644 --- a/versions/raml-10/raml-10.md +++ b/versions/raml-10/raml-10.md @@ -2065,11 +2065,11 @@ traits: Parameters may not be used within !include tags, that is, within the location of the file to be included. -### Optional Properties +### Declaring HTTP Methods as Optional -When defining resource types and traits, it can be useful to capture patterns that manifest several levels below the inheriting resource or method, without mandating the creation of the intermediate levels. For example, a resource type declaration may describe a body parameter that would be used if the API defines a post method for that resource, but applying the resource type to a resource without a post method should not create the post method. +When defining resource types, it can be useful to capture patterns that manifest several levels below the inheriting resource, without mandating the creation of the intermediate levels. For example, a resource type declaration may describe a body parameter that would be used if the API defines a post method for that resource, but applying the resource type to a resource without a post method should not create the post method. -To accommodate this need, a resource type or trait definition MAY append a question mark ("?") suffix to the name of any object-valued property that should not be applied if it doesn't already exist in the resource or method at the corresponding level. A property is considered object-valued if its value is of type object or of a type that has object at the base of its inheritance hierarchy. The question mark suffix indicates that the value of the property in the resource type or trait should be applied if the property name itself (without the question mark) is already defined (whether explicitly or implicitly) at the corresponding level in that resource or method. +To accommodate this need, a resource type definition MAY append a question mark ("?") suffix to the name of any method that should not be applied if it doesn't already exist in the resource at the corresponding level. The question mark suffix indicates that the value of the method property in the resource type should be applied if the method name itself (without the question mark) is already defined (whether explicitly or implicitly) at the corresponding level in that resource. The following example shows a resource type called corpResource with an optional post? property that defines a required header called X-Chargeback and also a custom parameter called TextAboutPost. If the inheriting resource defines a post method, it will include the X-Chargeback header requirement and TextAboutPost MUST be defined as well. If the inheriting resource does not define a post method, one will not have to define the X-Chargeback header or be forced to define the TextAboutPost parameter by dint of inheriting from the corpResource resource type. @@ -2096,29 +2096,7 @@ resourceTypes: # not required; same for the X-Chargeback header ``` -Note that a question mark can also appear as the last character of a RAML Type property name. If you wish to use this syntax within a Resource Type or Trait you should escape it with a backslash ( "\?"). Consider an example of body type defined inside trait by a properties set: - -```yaml -#%RAML 1.0 -title: Example of Optional Properties of Types Defined in Trait -traits: - - hasPayload: - body: - application/json: - properties: - name: - address\?: - location?: -/servers: - post: - is: [ hasPayload ] - # will have application/json body with 'name' required property, - # 'address' optional property, but without 'location' property -``` - -The POST:/servers method obtains an application/json body with with 'name' required property, 'address' optional property, but without 'location' property. - -It is important to note that this feature applies only to object-valued properties; the appending of the optional marker ("?") to a scalar- or array-valued property such as description or security schemes MUST be rejected by RAML parsers. +Note that a question mark can also appear as the last character of a RAML Type property name. If you wish to use this syntax within a resource type you should escape it with a backslash ( "\?"). ### Applying Resource Types and Traits From a2040a138b736d6a6b29d975554d46d0851e2045 Mon Sep 17 00:00:00 2001 From: Christian Vogel Date: Mon, 14 Mar 2016 12:50:48 +0000 Subject: [PATCH 039/241] clarifies that any trait that is applied to a method, gets applied in a specific order - from left to right --- versions/raml-10/raml-10.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/versions/raml-10/raml-10.md b/versions/raml-10/raml-10.md index 202a7170..95f85697 100644 --- a/versions/raml-10/raml-10.md +++ b/versions/raml-10/raml-10.md @@ -2124,7 +2124,7 @@ It is important to note that this feature applies only to object-valued properti The OPTIONAL **type** property applies a resource type to a resource, so that the resource inherits the resource type's characteristics. The value of the **type** property is either a) a name of a resource type declared in the resourceTypes declaration, or b) an inline (anonymous) resource type declaration. Resource type definitions MUST NOT incorporate nested resources; they cannot be used to generate nested resources when they are applied to a resource, and they do not apply to its existing nested resources. -The OPTIONAL **is** property applies any number of traits to a method, so that the method inherits the trait's or traits' characteristics. The value of the is attribute is an array of any number of elements, each of which is either a) a name of a trait declared in the traits declaration, or b) an inline (anonymous) trait declaration. Trait definitions MUST NOT incorporate nested resources. +The OPTIONAL **is** property applies any number of traits to a method, so that the method inherits the trait's or traits' characteristics. The value of the is attribute is an array of any number of elements, each of which is either a) a name of a trait declared in the traits declaration, or b) an inline (anonymous) trait declaration. The order of a trait getting applied to a method is from left to right; according to the traits defined in the **is** property. Trait definitions MUST NOT incorporate nested resources. A trait may also be applied to a resource by using the **is** key, which is equivalent to applying the trait to all methods for that resource, whether declared explicitly in the resource definition or inherited from a resource type. From 7e311f1db5e793e21eb1f9b31309b609c59728d1 Mon Sep 17 00:00:00 2001 From: Christian Vogel Date: Wed, 16 Mar 2016 10:15:46 +0000 Subject: [PATCH 040/241] changed examples for libraries a bit so that it is more clear how to use assets from a library --- versions/raml-10/raml-10.md | 8 +++++++- 1 file changed, 7 insertions(+), 1 deletion(-) diff --git a/versions/raml-10/raml-10.md b/versions/raml-10/raml-10.md index 491b9123..4280d432 100644 --- a/versions/raml-10/raml-10.md +++ b/versions/raml-10/raml-10.md @@ -3075,8 +3075,14 @@ resourceTypes: file: get: is: drm + responses: + 201: + body: + application/json: + type: file-type.File put: is: drm + ``` ```yaml @@ -3101,7 +3107,7 @@ get: 200: body: application/json: - type: files.file-type.File + type: files.file-type.File # invalid - no chaining allowed ``` ### Overlays and Extensions From bde5b7d0b2484d79b60e26808feec2db90f3dd4a Mon Sep 17 00:00:00 2001 From: Christian Vogel Date: Wed, 16 Mar 2016 10:36:18 +0000 Subject: [PATCH 041/241] extended the initial example to be more descriptive on how a single or multiple example definition looks at various level in your API --- versions/raml-10/raml-10.md | 39 ++++++++++++++++++++++++++++--------- 1 file changed, 30 insertions(+), 9 deletions(-) diff --git a/versions/raml-10/raml-10.md b/versions/raml-10/raml-10.md index a56145de..b2233ddf 100644 --- a/versions/raml-10/raml-10.md +++ b/versions/raml-10/raml-10.md @@ -1416,11 +1416,12 @@ value: #### Example on how to define example/examples in RAML -The following illustrates usage of both example and examples properties. +The following illustrates usage of both example and examples properties at different levels of a RAML API. ```yaml #%RAML 1.0 title: API with Examples + types: User: type: object @@ -1436,14 +1437,34 @@ types: name: string address?: string value? : string - examples: - acme: - name: Acme - softwareCorp: - value: # validate against the available facets for the map value of an example - name: Software Corp - address: 35 Central Street - value: Gold # validate against instance of the `value` property +/organisation: + post: + headers: + UserID: + description: the identifier for the user that posts a new organisation + type: string + example: SWED-123 # single scalar example + body: + application/json: + type: Org + example: # single request body example + name: Doe Enterprise + value: Silver + get: + description: Returns an organisation entity. + responses: + 201: + body: + application/json: + type: Org + examples: + acme: + name: Acme + softwareCorp: + value: # validate against the available facets for the map value of an example + name: Software Corp + address: 35 Central Street + value: Gold # validate against instance of the `value` property ``` ### Using Types in RAML From 3f0a2ba176b898dee9742b61a35a0a411e8cfeb1 Mon Sep 17 00:00:00 2001 From: Christian Vogel Date: Wed, 16 Mar 2016 13:25:28 +0000 Subject: [PATCH 042/241] removed notation of having the question mark as a last character for properties that does not indicate it automatically as an optional property --- versions/raml-10/raml-10.md | 2 -- 1 file changed, 2 deletions(-) diff --git a/versions/raml-10/raml-10.md b/versions/raml-10/raml-10.md index 4ade19bd..c2d24493 100644 --- a/versions/raml-10/raml-10.md +++ b/versions/raml-10/raml-10.md @@ -2096,8 +2096,6 @@ resourceTypes: # not required; same for the X-Chargeback header ``` -Note that a question mark can also appear as the last character of a RAML Type property name. If you wish to use this syntax within a resource type you should escape it with a backslash ( "\?"). - ### Applying Resource Types and Traits The OPTIONAL **type** property applies a resource type to a resource, so that the resource inherits the resource type's characteristics. The value of the **type** property is either a) a name of a resource type declared in the resourceTypes declaration, or b) an inline (anonymous) resource type declaration. Resource type definitions MUST NOT incorporate nested resources; they cannot be used to generate nested resources when they are applied to a resource, and they do not apply to its existing nested resources. From b3926934fff5a7e82950f29b6d08c804cddfea95 Mon Sep 17 00:00:00 2001 From: Christian Vogel Date: Thu, 17 Mar 2016 08:51:15 +0000 Subject: [PATCH 043/241] changing 'mediaTypes' back to 'mediaType' and add text that says that the value can be either a sequence or string --- versions/raml-10/raml-10.md | 40 ++++++++++++++++++++++--------------- 1 file changed, 24 insertions(+), 16 deletions(-) diff --git a/versions/raml-10/raml-10.md b/versions/raml-10/raml-10.md index b18651bc..a4ccf8a6 100644 --- a/versions/raml-10/raml-10.md +++ b/versions/raml-10/raml-10.md @@ -105,7 +105,7 @@ This example shows a small part of a RAML API definition for the GitHub v3 publi title: GitHub API version: v3 baseUri: https://api.github.com -mediaTypes: [ application/json ] +mediaType: application/json securitySchemes: - oauth_2_0: !include securitySchemes/oauth_2_0.raml types: @@ -139,7 +139,7 @@ The following table enumerates the possible properties at the root of a RAML doc | baseUri? | A URI that's to be used as the base of all the resources' URIs. Often used as the base of the URL of each resource, containing the location of the API. Can be a [template URI](#template-uri). See section [Base URI and Base URI Parameters](#base-uri-and-base-uri-parameters) for more information. | baseUriParameters? | Named parameters used in the baseUri (template). See section [Base URI and Base URI Parameters](#base-uri-and-base-uri-parameters) for more information. | protocols? | The protocols supported by the API. The protocols property MUST contain one or more of the supported protocols: "HTTP", "HTTPS". (case-insensitive). -| mediaTypes? | Default media types to use for request and response bodies (payloads), e.g. "application/json" +| mediaType? | Default media types to use for request and response bodies (payloads), e.g. "application/json" | securedBy? | The security schemes that apply to every resource and method in the API. See section [Applying Security Schemes](#applying-security-schemes) for more information. | /<relativeUri>? | The resources of the API, identified as relative URIs that begin with a slash (/). Every property whose key begins with a slash (/), and is either at the root of the API definition or is the child property of a resource property, is a resource property, e.g.: /users, /{groupId}, etc. | documentation? | Additional overall documentation for the API. See section [User Documentation](#user-documentation) for more information. @@ -258,24 +258,32 @@ baseUri: https://na1.salesforce.com/services/data/{version}/chatter ### Default Media Types -The media types expected from API requests that contain a body, and returned by API responses, can be defaulted by specifying the OPTIONAL **mediaTypes** property, so they do not need to be specified within every body definition. +The media types expected from API requests that contain a body, and returned by API responses, can be defaulted by specifying the OPTIONAL **mediaType** property, so they do not need to be specified within every body definition. -The value of the mediaTypes property MUST be a sequence of media type strings conforming to the media type specification in [RFC6838](https://tools.ietf.org/html/rfc6838); with the premise that all of them are described by exactly the same types and/or examples. +The value of the mediaType property MUST be a sequence of media type strings or a single string if there is only one default media; with the premise that all of them are described by exactly the same types and/or examples. Each value need to conform to the media type specification in [RFC6838](https://tools.ietf.org/html/rfc6838). -This example shows a RAML snippet for an API that accepts and returns JSON- and XML-formatted bodies. If the remainder of this API's specification doesn't explicitly specify another media type, this API only accepts and returns JSON- and XML-formatted bodies. +This example shows a RAML snippet for an API that accepts and returns a JSON-formatted body. If the remainder of this API's specification doesn't explicitly specify another media type, this API only accepts and returns JSON-formatted bodies. ```yaml #%RAML 1.0 title: New API -mediaTypes: [ application/json, application/xml ] +mediaType: application/json ``` -Default media types can be overridden by defining a `mediaType` node explicitly to a [body](#bodies) of an API request or response. When one defines a root-level `mediaTypes` node and then override that in a body by defining explicitly another or the same media type node, none of the root level media types apply to that node, other than the media types explicitly defined within that node. The example below shows a RAML snippet that illustrates that behavior. The resource `/list` returns a `Person[]` body represented as either JSON or XML. On the other hand, the resource `/send` overrides the default media types with an explicit definition of an `application/json` node and therefore only accepts a JSON-formatted body. +Or the alternative syntax if there is more than one default media type. ```yaml #%RAML 1.0 title: New API -mediaTypes: [ application/json, application/xml ] +mediaType: [ application/json, application/xml ] +``` + +Default media types can be overridden by defining a `mediaType` node explicitly to a [body](#bodies) of an API request or response. When one defines a root-level `mediaType` node and then override that in a body by defining explicitly another or the same media type node, none of the root level media types apply to that node, other than the media types explicitly defined within that node. The example below shows a RAML snippet that illustrates that behavior. The resource `/list` returns a `Person[]` body represented as either JSON or XML. On the other hand, the resource `/send` overrides the default media types with an explicit definition of an `application/json` node and therefore only accepts a JSON-formatted body. + +```yaml +#%RAML 1.0 +title: New API +mediaType: [ application/json, application/xml ] types: Person: Another: @@ -348,7 +356,7 @@ succinct than JSON and XML schemas while retaining their flexibility and express ```yaml #%RAML 1.0 title: My API with Types -mediaTypes: [ application/json ] +mediaType: application/json types: Org: type: object @@ -1845,7 +1853,7 @@ The following example illustrates various combinations of both default and non-d ```yaml #%RAML 1.0 title: Example of request bodies -mediaTypes: [ application/json ] +mediaType: application/json types: User: properties: @@ -1892,7 +1900,7 @@ The following example illustrates some possible responses. ```yaml #%RAML 1.0 title: Example with responses -mediaTypes: [ application/json ] +mediaType: application/json types: Invoice: properties: @@ -2050,7 +2058,7 @@ To apply these functions, append them to the parameter name within the double an #%RAML 1.0 title: Example API version: v1 -mediaTypes: [ application/json ] +mediaType: application/json types: Users: !include types/users.raml User: !include types/user.raml @@ -2612,7 +2620,7 @@ The following is an example of various annotation type declarations and the appl ```yaml #%RAML 1.0 title: Illustrating annotations -mediaTypes: [ application/json ] +mediaType: application/json annotationTypes: experimental: feedbackRequested: @@ -2679,7 +2687,7 @@ The example below, a small subset of the previous example, shows an explicit dec ```yaml #%RAML 1.0 title: Testing annotations -mediaTypes: [ application/json ] +mediaType: application/json annotationTypes: testHarness: type: string @@ -2692,7 +2700,7 @@ The following is semantically equivalent but relies on the implicit default decl ```yaml #%RAML 1.0 title: Testing annotations -mediaTypes: [ application/json ] +mediaType: application/json annotationTypes: testHarness: /users: @@ -2728,7 +2736,7 @@ The following example illustrates applying some restrictions on the allowed targ ```yaml #%RAML 1.0 title: Illustrating allowed targets -mediaTypes: [ application/json ] +mediaType: application/json annotationTypes: meta-resource-method: allowedTargets: [ Resource, Method ] From 82ab58b79ed2d717b369fa6f5504e6c1e2d8dd59 Mon Sep 17 00:00:00 2001 From: Christian Vogel Date: Thu, 17 Mar 2016 09:07:14 +0000 Subject: [PATCH 044/241] modified text to distinct between 'apply' and 'incorporate' --- versions/raml-10/raml-10.md | 15 +++++++++++++-- 1 file changed, 13 insertions(+), 2 deletions(-) diff --git a/versions/raml-10/raml-10.md b/versions/raml-10/raml-10.md index 95f85697..b407ff52 100644 --- a/versions/raml-10/raml-10.md +++ b/versions/raml-10/raml-10.md @@ -1980,6 +1980,17 @@ traits: - rateLimited: !include traits/rate-limited.raml ``` +Neither resource types nor traits are allowed to incorporate nested resources. Therefore, the following example is invalid: + +```yaml +resourceTypes: + hasGroups: + get: + patch: + delete: + /groups: +``` + ### Usage The OPTIONAL **usage** property of a resource type or trait provides instructions on how and when the resource type or trait should be used. Documentation generators MUST convey this property as characteristics of the resource and method, respectively. However, the resources and methods MUST NOT inherit the usage property: neither resources nor methods allow a property named usage. @@ -2122,9 +2133,9 @@ It is important to note that this feature applies only to object-valued properti ### Applying Resource Types and Traits -The OPTIONAL **type** property applies a resource type to a resource, so that the resource inherits the resource type's characteristics. The value of the **type** property is either a) a name of a resource type declared in the resourceTypes declaration, or b) an inline (anonymous) resource type declaration. Resource type definitions MUST NOT incorporate nested resources; they cannot be used to generate nested resources when they are applied to a resource, and they do not apply to its existing nested resources. +The OPTIONAL **type** property applies a resource type to a resource, so that the resource inherits the resource type's characteristics. The value of the **type** property is either a) a name of a resource type declared in the resourceTypes declaration, or b) an inline (anonymous) resource type declaration. Resource type definitions do not apply to existing nested resources. -The OPTIONAL **is** property applies any number of traits to a method, so that the method inherits the trait's or traits' characteristics. The value of the is attribute is an array of any number of elements, each of which is either a) a name of a trait declared in the traits declaration, or b) an inline (anonymous) trait declaration. The order of a trait getting applied to a method is from left to right; according to the traits defined in the **is** property. Trait definitions MUST NOT incorporate nested resources. +The OPTIONAL **is** property applies any number of traits to a method, so that the method inherits the trait's or traits' characteristics. The value of the is attribute is an array of any number of elements, each of which is either a) a name of a trait declared in the traits declaration, or b) an inline (anonymous) trait declaration. The order of a trait getting applied to a method is from left to right; according to the traits defined in the **is** property. Trait definitions do not apply to nested resources. A trait may also be applied to a resource by using the **is** key, which is equivalent to applying the trait to all methods for that resource, whether declared explicitly in the resource definition or inherited from a resource type. From 491a8f09787cee78a15cccb8cfba3d58cfccbf64 Mon Sep 17 00:00:00 2001 From: Christian Vogel Date: Thu, 17 Mar 2016 09:31:54 +0000 Subject: [PATCH 045/241] removed occurrences of sequences from global definitions except 'documentation' as per issue #306 --- versions/raml-10/raml-10.md | 318 ++++++++++++++++++------------------ 1 file changed, 159 insertions(+), 159 deletions(-) diff --git a/versions/raml-10/raml-10.md b/versions/raml-10/raml-10.md index c4d5b206..dd34bdb6 100644 --- a/versions/raml-10/raml-10.md +++ b/versions/raml-10/raml-10.md @@ -107,12 +107,12 @@ version: v3 baseUri: https://api.github.com mediaType: application/json securitySchemes: - - oauth_2_0: !include securitySchemes/oauth_2_0.raml + oauth_2_0: !include securitySchemes/oauth_2_0.raml types: - Gist: !include types/gist.raml - Gists: !include types/gists.raml + Gist: !include types/gist.raml + Gists: !include types/gists.raml resourceTypes: - collection: !include types/collection.raml + collection: !include types/collection.raml traits: securedBy: [ oauth_2_0 ] /search: @@ -312,8 +312,8 @@ version: 1 baseUri: https://api.dropbox.com/{version} securedBy: [ oauth_2_0, oauth_1_0 ] securitySchemes: - - oauth_2_0: !include securitySchemes/oauth_2_0.raml - - oauth_1_0: !include securitySchemes/oauth_1_0.raml + oauth_2_0: !include securitySchemes/oauth_2_0.raml + oauth_1_0: !include securitySchemes/oauth_1_0.raml ``` ## RAML Data Types @@ -2038,11 +2038,11 @@ The following example builds on the previous one, but the the resource types and title: Example API version: v1 resourceTypes: - - collection: !include resourceTypes/collection.raml - - member: !include resourceTypes/member.raml + collection: !include resourceTypes/collection.raml + member: !include resourceTypes/member.raml traits: - - secured: !include traits/secured.raml - - rateLimited: !include traits/rate-limited.raml + secured: !include traits/secured.raml + rateLimited: !include traits/rate-limited.raml ``` Neither resource types nor traits are allowed to incorporate nested resources. Therefore, the following example is invalid: @@ -2113,30 +2113,30 @@ types: Users: !include types/users.raml User: !include types/user.raml resourceTypes: - - collection: - get: - responses: - 200: - body: - type: <> # e.g. Users - post: - responses: - 200: - body: - type: <> # e.g. User - - member: - get: - responses: - 200: - body: - type: <> # e.g. User + collection: + get: + responses: + 200: + body: + type: <> # e.g. Users + post: + responses: + 200: + body: + type: <> # e.g. User + member: + get: + responses: + 200: + body: + type: <> # e.g. User traits: - - secured: - description: Some requests require authentication - queryParameters: - <>: # e.g. get: - description: A <>-token pair is required # e.g. A get-token pair... - example: <>=h8duh3uhhu38 # e.g. get=h8duh3uhhu38 + secured: + description: Some requests require authentication + queryParameters: + <>: # e.g. get: + description: A <>-token pair is required # e.g. A get-token pair... + example: <>=h8duh3uhhu38 # e.g. get=h8duh3uhhu38 ``` Parameters may not be used within !include tags, that is, within the location of the file to be included. @@ -2153,12 +2153,12 @@ The following example shows a resource type called corpResource with an optional #%RAML 1.0 title: Example of Optional Properties resourceTypes: - - corpResource: - post?: - description: Some info about <>. - headers: - X-Chargeback: - required: true + corpResource: + post?: + description: Some info about <>. + headers: + X-Chargeback: + required: true /servers: type: corpResource: @@ -2355,45 +2355,45 @@ title: Dropbox API version: 1 baseUri: https://api.dropbox.com/{version} securitySchemes: - - oauth_2_0: - description: | - Dropbox supports OAuth 2.0 for authenticating all API requests. - type: OAuth 2.0 - describedBy: - headers: - Authorization: - description: | - Used to send a valid OAuth 2 access token. Do not use - with the "access_token" query string parameter. - type: string - queryParameters: - access_token: - description: | - Used to send a valid OAuth 2 access token. Do not use together with - the "Authorization" header - type: string - responses: - 401: - description: | - Bad or expired token. This can happen if the user or Dropbox - revoked or expired an access token. To fix, you should re- - authenticate the user. - 403: - description: | - Bad OAuth request (wrong consumer key, bad nonce, expired - timestamp...). Unfortunately, re-authenticating the user won't help here. - settings: - authorizationUri: https://www.dropbox.com/1/oauth2/authorize - accessTokenUri: https://api.dropbox.com/1/oauth2/token - authorizationGrants: [ authorization_code, refresh_token ] - - oauth_1_0: - description: | - OAuth 1.0 continues to be supported for all API requests, but OAuth 2.0 is now preferred. - type: OAuth 1.0 - settings: - requestTokenUri: https://api.dropbox.com/1/oauth/request_token - authorizationUri: https://www.dropbox.com/1/oauth/authorize - tokenCredentialsUri: https://api.dropbox.com/1/oauth/access_token + oauth_2_0: + description: | + Dropbox supports OAuth 2.0 for authenticating all API requests. + type: OAuth 2.0 + describedBy: + headers: + Authorization: + description: | + Used to send a valid OAuth 2 access token. Do not use + with the "access_token" query string parameter. + type: string + queryParameters: + access_token: + description: | + Used to send a valid OAuth 2 access token. Do not use together with + the "Authorization" header + type: string + responses: + 401: + description: | + Bad or expired token. This can happen if the user or Dropbox + revoked or expired an access token. To fix, you should re- + authenticate the user. + 403: + description: | + Bad OAuth request (wrong consumer key, bad nonce, expired + timestamp...). Unfortunately, re-authenticating the user won't help here. + settings: + authorizationUri: https://www.dropbox.com/1/oauth2/authorize + accessTokenUri: https://api.dropbox.com/1/oauth2/token + authorizationGrants: [ authorization_code, refresh_token ] + oauth_1_0: + description: | + OAuth 1.0 continues to be supported for all API requests, but OAuth 2.0 is now preferred. + type: OAuth 1.0 + settings: + requestTokenUri: https://api.dropbox.com/1/oauth/request_token + authorizationUri: https://www.dropbox.com/1/oauth/authorize + tokenCredentialsUri: https://api.dropbox.com/1/oauth/access_token ``` #### describedBy @@ -2432,14 +2432,14 @@ title: Dropbox API version: 1 baseUri: https://api.dropbox.com/{version} securitySchemes: - - oauth_1_0: - description: | - OAuth 1.0 continues to be supported for all API requests, but OAuth 2.0 is now preferred. - type: OAuth 1.0 - settings: - requestTokenUri: https://api.dropbox.com/1/oauth/request_token - authorizationUri: https://www.dropbox.com/1/oauth/authorize - tokenCredentialsUri: https://api.dropbox.com/1/oauth/access_token + oauth_1_0: + description: | + OAuth 1.0 continues to be supported for all API requests, but OAuth 2.0 is now preferred. + type: OAuth 1.0 + settings: + requestTokenUri: https://api.dropbox.com/1/oauth/request_token + authorizationUri: https://www.dropbox.com/1/oauth/authorize + tokenCredentialsUri: https://api.dropbox.com/1/oauth/access_token ``` ##### OAuth 2.0 @@ -2461,37 +2461,37 @@ title: Dropbox API version: 1 baseUri: https://api.dropbox.com/{version} securitySchemes: - - oauth_2_0: - description: | - Dropbox supports OAuth 2.0 for authenticating all API requests. - type: OAuth 2.0 - describedBy: - headers: - Authorization: - description: | - Used to send a valid OAuth 2 access token. Do not use - with the "access_token" query string parameter. - type: string - queryParameters: - access_token: - description: | - Used to send a valid OAuth 2 access token. Do not use together with - the "Authorization" header - type: string - responses: - 401: - description: | - Bad or expired token. This can happen if the user or Dropbox - revoked or expired an access token. To fix, you should re- - authenticate the user. - 403: - description: | - Bad OAuth request (wrong consumer key, bad nonce, expired - timestamp...). Unfortunately, re-authenticating the user won't help here. - settings: - authorizationUri: https://www.dropbox.com/1/oauth2/authorize - accessTokenUri: https://api.dropbox.com/1/oauth2/token - authorizationGrants: [ authorization_code, refresh_token ] + oauth_2_0: + description: | + Dropbox supports OAuth 2.0 for authenticating all API requests. + type: OAuth 2.0 + describedBy: + headers: + Authorization: + description: | + Used to send a valid OAuth 2 access token. Do not use + with the "access_token" query string parameter. + type: string + queryParameters: + access_token: + description: | + Used to send a valid OAuth 2 access token. Do not use together with + the "Authorization" header + type: string + responses: + 401: + description: | + Bad or expired token. This can happen if the user or Dropbox + revoked or expired an access token. To fix, you should re- + authenticate the user. + 403: + description: | + Bad OAuth request (wrong consumer key, bad nonce, expired + timestamp...). Unfortunately, re-authenticating the user won't help here. + settings: + authorizationUri: https://www.dropbox.com/1/oauth2/authorize + accessTokenUri: https://api.dropbox.com/1/oauth2/token + authorizationGrants: [ authorization_code, refresh_token ] ``` ##### Basic Authentication @@ -2504,10 +2504,10 @@ title: Dropbox API version: 1 baseUri: https://api.dropbox.com/{version} securitySchemes: - - basic: - description: | - This API supports Basic Authentication. - type: Basic Authentication + basic: + description: | + This API supports Basic Authentication. + type: Basic Authentication ``` ##### Digest Authentication @@ -2520,10 +2520,10 @@ title: Dropbox API version: 1 baseUri: https://api.dropbox.com/{version} securitySchemes: - - digest: - description: | - This API supports DigestSecurityScheme Authentication. - type: Digest Authentication + digest: + description: | + This API supports DigestSecurityScheme Authentication. + type: Digest Authentication ``` ##### Pass Through @@ -2536,17 +2536,17 @@ title: Dropbox API version: 1 baseUri: https://api.dropbox.com/{version} securitySchemes: - - passthrough: - description: | - This API supports Pass Through Authentication. - type: Pass Through - describedBy: - queryParameters: - query: - type: string - headers: - api_key: - type: string + passthrough: + description: | + This API supports Pass Through Authentication. + type: Pass Through + describedBy: + queryParameters: + query: + type: string + headers: + api_key: + type: string ``` ##### x-<other> @@ -2559,21 +2559,21 @@ title: Custom API version: 1 baseUri: https://api.custom.com/{version} securitySchemes: - - custom_scheme: - description: | - A custom security scheme for authenticating requests. - type: x-custom - describedBy: - headers: - SpecialToken: - description: | - Used to send a custom token. - type: string - responses: - 401: - description: | - Bad token. - 403: + custom_scheme: + description: | + A custom security scheme for authenticating requests. + type: x-custom + describedBy: + headers: + SpecialToken: + description: | + Used to send a custom token. + type: string + responses: + 401: + description: | + Bad token. + 403: ``` #### Applying Security Schemes @@ -2592,8 +2592,8 @@ version: 1 baseUri: https://api.dropbox.com/{version} securedBy: [oauth_2_0] securitySchemes: - - oauth_2_0: !include securitySchemes/oauth_2_0.raml - - oauth_1_0: !include securitySchemes/oauth_1_0.raml + oauth_2_0: !include securitySchemes/oauth_2_0.raml + oauth_1_0: !include securitySchemes/oauth_1_0.raml /users: get: securedBy: [oauth_2_0, oauth_1_0] @@ -2607,10 +2607,10 @@ title: GitHub API version: v3 baseUri: https://api.github.com securitySchemes: - - oauth_2_0: !include securitySchemes/oauth_2_0.raml + oauth_2_0: !include securitySchemes/oauth_2_0.raml /users/{userid}/gists: - get: - securedBy: [null, oauth_2_0] + get: + securedBy: [null, oauth_2_0] ``` A resource can also be applied a list of security schemes using the **securedBy** attribute. This specifies that all methods of this particular resource (unless they have their own securedBy attribute) can be authenticated by any mentioned security scheme. Value of resources attribute overrides that of the root attribute. Security Schemes applied to a resource MUST NOT incorporate nested resources; they do not apply to its existing nested resources. @@ -2627,10 +2627,10 @@ title: GitHub API version: v3 baseUri: https://api.github.com securitySchemes: - - oauth_2_0: !include securitySchemes/oauth_2_0.raml + oauth_2_0: !include securitySchemes/oauth_2_0.raml /users/{userid}/gists: - get: - securedBy: [null, oauth_2_0: { scopes: [ ADMINISTRATOR ] } ] + get: + securedBy: [null, oauth_2_0: { scopes: [ ADMINISTRATOR ] } ] ``` The list of parameters that must and may be provided to the security scheme is specified by the security scheme type. From 18bd54210b8744122b709d3251bd4be9a96b475e Mon Sep 17 00:00:00 2001 From: Christian Vogel Date: Mon, 21 Mar 2016 10:00:23 +0000 Subject: [PATCH 046/241] removed 'displayName' from each node that is not allowed to have that property according to issue #222 --- versions/raml-10/raml-10.md | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/versions/raml-10/raml-10.md b/versions/raml-10/raml-10.md index dd34bdb6..1198e90c 100644 --- a/versions/raml-10/raml-10.md +++ b/versions/raml-10/raml-10.md @@ -1927,13 +1927,12 @@ The value of a response declaration is an object that may contain any of the fol |Property | Description | |:--------|:------------| -| displayName? | An alternate, human-friendly name for the response | description? | A longer, human-friendly description of the response | (<annotationName>) | Annotations to be applied to this response. Annotations are any property whose key begins with "(" and ends with ")" and whose name (the part between the beginning and ending parentheses) is a declared annotation name. See section [Annotations](#annotations) for more information. | headers? | Detailed information about any response headers returned by this method | body? | The body of the response -The OPTIONAL properties **displayName**, **description**, **headers**, **body**, and **annotations** have the same syntax and semantics as they do for [method declarations](methods), but applied to HTTP responses rather than HTTP requests. +The OPTIONAL properties **description**, **headers**, **body**, and **annotations** have the same syntax and semantics as they do for [method declarations](methods), but applied to HTTP responses rather than HTTP requests. The following example illustrates some possible responses. @@ -3060,7 +3059,8 @@ A library is an object whose allowed properties are enumerated in the following |Property | Description | |:--------|:------------| -| types?
    chemas?
    resourceTypes?
    traits?
    securitySchemes?
    annotationTypes?
    (<annotationName>)?
    uses? | The definition of each property is the same as that of the corresponding property in the root of a RAML document. Annotation properties are allowed as in any other RAML document. +| types?
    schemas?
    resourceTypes?
    traits?
    securitySchemes?
    annotationTypes?
    (<annotationName>)?
    uses? | The definition of each property is the same as that of the corresponding property in the root of a RAML document. Annotation properties are allowed as in any other RAML document. +| usage | Describes the content or purpose of a specific library. The content may be described in markdown. The following example shows a simple library as a standalone, reusable RAML fragment document. @@ -3181,7 +3181,7 @@ The behavior-invariance restrictions of an overlay are defined as follows: after |Property | Allowed differences | |:--------|:------------| -| title
    description
    documentation
    displayName
    usage
    example | The merged tree may include new properties of this type, or properties with different values than those in the master tree. +| title
    description
    documentation
    usage
    example | The merged tree may include new properties of this type, or properties with different values than those in the master tree. | types | In addition to allowed differences described elsewhere in this table, the merged tree may also include new data types. | annotationTypes | The merged tree may include new annotation types, or new values for existing annotation types, as long as all annotations in the merged API definition validate against the annotation types in the merged tree. | any annotation property | The merged tree may include new annotations of annotation types declared in the merged tree, or annotations with different values than those in the master tree. From 8a2c6ef4ca37b8d1a0b1adec54ef6ea501da7c89 Mon Sep 17 00:00:00 2001 From: Christian Vogel Date: Mon, 21 Mar 2016 11:46:46 +0000 Subject: [PATCH 047/241] removed inline + include support for traits, resource types, and security schemes according to issue 321 --- versions/raml-10/raml-10.md | 18 +++++++----------- 1 file changed, 7 insertions(+), 11 deletions(-) diff --git a/versions/raml-10/raml-10.md b/versions/raml-10/raml-10.md index 1198e90c..36b839b2 100644 --- a/versions/raml-10/raml-10.md +++ b/versions/raml-10/raml-10.md @@ -1986,23 +1986,23 @@ A resource type is a partial resource definition that, like a resource, can spec A trait is a partial method definition that, like a method, can provide method-level properties such as description, headers, query string parameters, and responses. Methods that use one or more traits inherit those traits' properties. Resources and resource types can also use, and thus inherit from, one or more traits, which then apply to all of their methods. Traits are related to methods through a mixing pattern. -Resources may specify the resource type from which they inherit using the type property. The resource type may be defined inline as the value of the type property (directly or via an !include), or the value of the type property may be the name of a resource type defined within the root-level resourceTypes property or in a library. +Resources may specify the resource type from which they inherit using the type property. The resource type may be the name of a resource type defined within the root-level resourceTypes property or in a library. -Similarly, methods may specify one or more traits from which they inherit using the is property. Its value is an array of traits. A resource may also use this property, in which case the array of traits is applied to all its methods. Each trait element in that array may be defined inline (directly or via an !include), or it may be the name of a trait defined within the root-level traits property or in a library. +Similarly, methods may specify one or more traits from which they inherit using the is property. Its value is an array of traits. A resource may also use this property, in which case the array of traits is applied to all its methods. Each trait element in that array may be the name of a trait defined within the root-level traits property or in a library. Resource type definitions MUST NOT incorporate nested resources; they cannot be used to generate nested resources when they are applied to a resource, and they do not apply to its existing nested resources. ### Declaration -Resource types may be declared via the OPTIONAL **resourceTypes** property at the root of the API definition. The value of this property is an object whose property names become names of resource types that can be referenced throughout the API, and whose property values are resource type declarations. Resource types may also be declared inline, anonymously. +Resource types may be declared via the OPTIONAL **resourceTypes** property at the root of the API definition. The value of this property is an object whose property names become names of resource types that can be referenced throughout the API, and whose property values are resource type declarations. -Similarly, traits may be declared via the OPTIONAL **traits** property at the root of the API definition. The value of this property is an object whose property names become names of traits that can be referenced throughout the API, and whose property values are trait declarations. Traits may also be declared inline, anonymously. +Similarly, traits may be declared via the OPTIONAL **traits** property at the root of the API definition. The value of this property is an object whose property names become names of traits that can be referenced throughout the API, and whose property values are trait declarations. Resource type and trait declarations can have the following properties, in addition to all the properties that resources and methods may have, respectively (except that resource type declarations MUST NOT have nested resource properties). | Property | Definition | |:---------|:-----------| -| usage? | Instructions on how and when to use this resource type in a RAML spec +| usage? | The OPTIONAL **usage** property of a resource type or trait provides instructions on how and when the resource type or trait should be used. Documentation generators MUST convey this property as characteristics of the resource and method, respectively. However, the resources and methods MUST NOT inherit the usage property: neither resources nor methods allow a property named usage. | uses? | You may import library locally here it contents is accessible only inside of this trait The following example illustrates the declaration of several resource types and traits. @@ -2055,10 +2055,6 @@ resourceTypes: /groups: ``` -### Usage - -The OPTIONAL **usage** property of a resource type or trait provides instructions on how and when the resource type or trait should be used. Documentation generators MUST convey this property as characteristics of the resource and method, respectively. However, the resources and methods MUST NOT inherit the usage property: neither resources nor methods allow a property named usage. - ### Resource Type and Trait Parameters The declarations of resource types and traits MAY contain parameters, whose values MUST be specified when applying the resource type or trait, UNLESS the parameter corresponds to a reserved parameter name, in which case its value MUST be provided by the processing application. @@ -2173,9 +2169,9 @@ resourceTypes: ### Applying Resource Types and Traits -The OPTIONAL **type** property applies a resource type to a resource, so that the resource inherits the resource type's characteristics. The value of the **type** property is either a) a name of a resource type declared in the resourceTypes declaration, or b) an inline (anonymous) resource type declaration. Resource type definitions do not apply to existing nested resources. +The OPTIONAL **type** property applies a resource type to a resource, so that the resource inherits the resource type's characteristics. The value of the **type** property is a name of a resource type declared in the resourceTypes declaration. Resource type definitions do not apply to existing nested resources. -The OPTIONAL **is** property applies any number of traits to a method, so that the method inherits the trait's or traits' characteristics. The value of the is attribute is an array of any number of elements, each of which is either a) a name of a trait declared in the traits declaration, or b) an inline (anonymous) trait declaration. The order of a trait getting applied to a method is from left to right; according to the traits defined in the **is** property. Trait definitions do not apply to nested resources. +The OPTIONAL **is** property applies any number of traits to a method, so that the method inherits the trait's or traits' characteristics. The value of the is attribute is an array of any number of elements, each of which is a name of a trait declared in the traits declaration. The order of a trait getting applied to a method is from left to right; according to the traits defined in the **is** property. Trait definitions do not apply to nested resources. A trait may also be applied to a resource by using the **is** key, which is equivalent to applying the trait to all methods for that resource, whether declared explicitly in the resource definition or inherited from a resource type. From 50e2992a7fb3e20c1e6d1b8de16da6d3e6402a45 Mon Sep 17 00:00:00 2001 From: Christian Vogel Date: Tue, 22 Mar 2016 10:35:38 +0000 Subject: [PATCH 048/241] added ABNF notation for first line of every RAML document --- versions/raml-10/raml-10.md | 8 ++++++-- 1 file changed, 6 insertions(+), 2 deletions(-) diff --git a/versions/raml-10/raml-10.md b/versions/raml-10/raml-10.md index 1198e90c..11f37e99 100644 --- a/versions/raml-10/raml-10.md +++ b/versions/raml-10/raml-10.md @@ -82,9 +82,13 @@ RAML API definitions are YAML 1.2-compliant documents that begin with a REQUIRED title: My API ``` -The first line of a RAML API definition document MUST begin with the text _#%RAML_ followed by a single space followed by the text _1.0_ and nothing else before the end of the line. (RAML fragment documents begin similarly with the RAML version comment and a fragment identifier, but are not in themselves RAML API definition documents. See the section about [Modularization](#modularization) for more information.) +The first line of a RAML specification compliant document MUST match the [IETF RFC5234](https://tools.ietf.org/html/rfc5234) – Augmented BNF for Syntax Specifications: -This specification defines the media type _application/raml+yaml_ for RAML API definition documents, for documents that contain sections of RAML markup to be included in such API definitions and that are not more specifically described by another media type such as _application/schema+json_, and for overlay and extension documents that yield RAML API definition documents upon processing. The recommended filename extension for such files is _.raml_. +“#%RAML” SP “1.0” SP [FragmentType] CRLF + +With the _FragmentType_ being NOT ALLOWED in API definitions, and is OPTIONAL for the specification of RAML fragment documents. RAML fragment documents are reusable RAML modules that are referenced or included into a larger API definition. Please refer to the [Modularization](#modularization) section for more information about RAML fragments. + +The media type _application/raml+yaml_ and its associated file extension _.raml_ SHALL be used to designate files containing RAML API definitions, RAML fragments and files that contain RAML markup. RAML is also capable of including documents with other media types, e.g., “application/schema+json”, “application/yaml”. In order to facilitate the automated processing of RAML documents, RAML imposes some restrictions and requirements in addition to the core YAML 1.2 specification. The following list enumerates some of these requirements and restrictions: From 191b4a902c7245941f43e8a533a1d32b7177eec6 Mon Sep 17 00:00:00 2001 From: Christian Vogel Date: Tue, 22 Mar 2016 11:17:50 +0000 Subject: [PATCH 049/241] removed polymorphism section and moved examples for discriminators up to the object type section; as well as changed discription for discriminator and discriminatorValue --- versions/raml-10/raml-10.md | 203 +++++++++++++----------------------- 1 file changed, 70 insertions(+), 133 deletions(-) diff --git a/versions/raml-10/raml-10.md b/versions/raml-10/raml-10.md index 11f37e99..b75184d4 100644 --- a/versions/raml-10/raml-10.md +++ b/versions/raml-10/raml-10.md @@ -460,8 +460,8 @@ All types that have the built-in object type at the root of their inheritance tr | maxProperties? | The maximum number of properties allowed for instances of this type. | additionalProperties? | JSON schema style syntax for declaring maps. See section [Map Types](#map-types) for more information. | patternProperties? | JSON schema style syntax for declaring key restricted maps. See section [Map Types](#map-types) for more information. -| discriminator? | Type property name to be used as discriminator, or boolean -| discriminatorValue? | The value of discriminator for the type. +| discriminator? | You may use the `discriminator` property to be able to discriminate the concrete type of an individual object at runtime when, for example, payloads contain ambiguous types (achieved via unions or inheritance). The value must correspond to a name of one of the `properties` that are defined inside a type declaration. The `discriminator` property can not be defined for inline type declarations and should only be used for scalar-valued properties. See an example on how to use `discriminator` [here](#using-discriminator-example).

    **Default:** the name of the type +| discriminatorValue? | You may use the `discriminatorValue` property if a type also defined the `discriminator` property. The value of this property should be a valid value of the property with the name equal to the value of the `discriminator` property; and its being used to identify the declaring type. This value should be unique in the hierarchy of the type. See an example on how to use `discriminatorValue` [here](#using-discriminator-example). An object type is created by explicitly inheriting from the built-in type object: @@ -659,6 +659,74 @@ types: type: Method ``` +#### Using Discriminator Example + +Here's an example that illustrates how to use `discriminator`: + +```yaml +#%RAML 1.0 +title: My API With Types +types: + Person: + type: object + discriminator: kind # refers to the `kind` property of object `Person` + properties: + kind: string # contains name of the kind of a `Person` instance + name: string + Employee: # kind may equal to `Employee` + type: Person + properties: + employeeId: string + User: # kind may equal to `User` + type: Person + properties: + userId: string +``` + +```yaml +data: + - name: A User + userId: 111 + kind: User + - name: An Employee + employeeId: 222 + kind: Employee +``` + +You can also override the value of the discriminator for each individual concrete class. In the following example we will replace the default type discriminator values by their lowercase versions using `discriminatorValue`: + +```yaml +#%RAML 1.0 +title: My API With Types +types: + Person: + type: object + discriminator: kind + properties: + name: string + kind: string + Employee: + type: Person + discriminatorValue: employee # override default + properties: + employeeId: string + User: + type: Person + discriminatorValue: user # override default + properties: + userId: string +``` + +```yaml +data: + - name: A User + userId: 111 + kind: user + - name: An Employee + employeeId: 222 + kind: employee +``` + ### Array Types Array Types are declared by using the array qualifier at the end of a Type Expression. If you are defining a top-level Array Type ( like the example below ), you can pass the following additional properties to further restrict its behavior. @@ -1260,137 +1328,6 @@ title: My API With Types type: number ``` -### Runtime Polymorphism (Discriminators) - -When payloads contain ambiguous types ( achieved via unions or inheritance ) it is often impossible to discriminate the concrete type of an individual object at runtime ( for example when deserializing the payload into a statically typed language ) - -RAML provides a pragmatic solution to this problem: You can store the actual type of an object as a string. - -To indicate that a certain family of types is using the "discriminator" convention, simply set it to true on a common supertype. - -```yaml -#%RAML 1.0 -title: My API With Types -types: - Person: - type: object - discriminator: true - properties: - name: string - Employee: - type: Person - properties: - employeeId: string - User: - type: Person - properties: - userId: string -``` - -```yaml -#%RAML 1.0 -data: - - name: A User - userId: 111 - discriminator: User - - name: An Employee - employeeId: 222 - discriminator: Employee -``` - -When a type belongs to a family of types that has the discriminator facet set to true, then instances of such class must have a discriminator property holding the name of the class. You can customize the name of the discriminator property by using a string value instead of a boolean value. - -Here's the same example, but this time we customize the property that holds the type name: - -```yaml -#%RAML 1.0 -title: My API With Types -types: - Person: - type: object - discriminator: kind - properties: - kind: string - name: string - Employee: - type: Person - properties: - employeeId: string - User: - type: Person - properties: - userId: string -``` - -```yaml -#%RAML 1.0 -data: - - name: A User - userId: 111 - kind: User - - name: An Employee - employeeId: 222 - kind: Employee -``` - -You can also override the value of the discriminator for each individual concrete class. In the following example we will replace the default type discriminator values by their lowercase versions: - -```yaml -#%RAML 1.0 -title: My API With Types -types: - Person: - type: object - discriminator: kind - properties: - name: string - kind: string - Employee: - type: Person - discriminatorValue: employee - properties: - employeeId: string - User: - type: Person - discriminatorValue: user - properties: - userId: string -``` - -```yaml -#%RAML 1.0 -data: - - name: A User - userId: 111 - kind: user - - name: An Employee - employeeId: 222 - kind: employee -``` - -When defining a discriminator for a family of types, all member types must be object types and have the discriminator property present ( or, if the name has been customized, the corresponding custom property ). This property must be of type string. - -```yaml -#%RAML 1.0 -title: My API With Types -types: - X: - type: object - properties: - discriminator: string - Y: - type: object - properties: - discriminator: string - Z: - type: object - properties: - discriminator: string - XYZ: - type: X | Y | Z - discriminator: true -``` - ### Defining Examples in RAML It is highly RECOMMENDED that API documentation include a rich selection of examples. RAML supports either the definition of multiple examples or a single one for any given instance of a type declaration. From e75eee4617795c8c8ab7012fe896b70fd9f91084 Mon Sep 17 00:00:00 2001 From: Christian Vogel Date: Tue, 22 Mar 2016 13:17:11 +0000 Subject: [PATCH 050/241] added more description around discriminator and discriminatorValue; as well as fixed some conceptial misunderstanding about discriminators --- versions/raml-10/raml-10.md | 18 ++++++++++++------ 1 file changed, 12 insertions(+), 6 deletions(-) diff --git a/versions/raml-10/raml-10.md b/versions/raml-10/raml-10.md index b75184d4..bff6174f 100644 --- a/versions/raml-10/raml-10.md +++ b/versions/raml-10/raml-10.md @@ -460,8 +460,8 @@ All types that have the built-in object type at the root of their inheritance tr | maxProperties? | The maximum number of properties allowed for instances of this type. | additionalProperties? | JSON schema style syntax for declaring maps. See section [Map Types](#map-types) for more information. | patternProperties? | JSON schema style syntax for declaring key restricted maps. See section [Map Types](#map-types) for more information. -| discriminator? | You may use the `discriminator` property to be able to discriminate the concrete type of an individual object at runtime when, for example, payloads contain ambiguous types (achieved via unions or inheritance). The value must correspond to a name of one of the `properties` that are defined inside a type declaration. The `discriminator` property can not be defined for inline type declarations and should only be used for scalar-valued properties. See an example on how to use `discriminator` [here](#using-discriminator-example).

    **Default:** the name of the type -| discriminatorValue? | You may use the `discriminatorValue` property if a type also defined the `discriminator` property. The value of this property should be a valid value of the property with the name equal to the value of the `discriminator` property; and its being used to identify the declaring type. This value should be unique in the hierarchy of the type. See an example on how to use `discriminatorValue` [here](#using-discriminator-example). +| discriminator? | You may use the `discriminator` property to be able to discriminate the concrete type of an individual object at runtime when, for example, payloads contain ambiguous types (achieved via unions or inheritance). The value must correspond to a name of one of the `properties` that are defined inside a type declaration. The `discriminator` property can not be defined for inline type declarations and should only be used for scalar-valued properties. See section [Using Discriminator](#using-discriminator) for more information. +| discriminatorValue? | You may use the `discriminatorValue` property if a type also defined the `discriminator` property. The value of this property should be a valid value of the property with the name equal to the value of the `discriminator` property; and its being used to identify the declaring type. This value should be unique in the hierarchy of the type. See section [Using Discriminator](#using-discriminator) for more information.

    **Default:** the name of the type where the discriminator is applied to An object type is created by explicitly inheriting from the built-in type object: @@ -659,7 +659,13 @@ types: type: Method ``` -#### Using Discriminator Example +#### Using Discriminator + +When payloads contain ambiguous types (achieved via unions or inheritance) it is often impossible to discriminate the concrete type of an individual object at runtime (for example when deserializing the payload into a statically typed language). + +A RAML processor may provide an implementation that automatically select a concrete type from a set of possible types, but one of the simplest options is to actually store some unique value associated with the type inside the object. + +The `discriminator` property allows you to set the name of an object property which will be used to discriminate the concrete type, and `discriminatorValue` stores the actual value that may identify the type of an individual object. By default, the value of `discriminatorValue` is the name of the type. Here's an example that illustrates how to use `discriminator`: @@ -673,11 +679,11 @@ types: properties: kind: string # contains name of the kind of a `Person` instance name: string - Employee: # kind may equal to `Employee` + Employee: # kind may equal to `Employee; default value for `discriminatorValue` type: Person properties: employeeId: string - User: # kind may equal to `User` + User: # kind may equal to `User`; default value for `discriminatorValue` type: Person properties: userId: string @@ -693,7 +699,7 @@ data: kind: Employee ``` -You can also override the value of the discriminator for each individual concrete class. In the following example we will replace the default type discriminator values by their lowercase versions using `discriminatorValue`: +You can also override the default for `discriminatorValue` for each individual concrete class. In the following example we will replace the default by their lowercase versions using `discriminatorValue`: ```yaml #%RAML 1.0 From 6dc9cb9fdac2239100fca3c2040a2e99e28f3bde Mon Sep 17 00:00:00 2001 From: Christian Vogel Date: Wed, 23 Mar 2016 13:17:37 +0000 Subject: [PATCH 051/241] added some additional clarification that you can not define discriminators for inline type declarations --- versions/raml-10/raml-10.md | 21 ++++++++++++++++++++- 1 file changed, 20 insertions(+), 1 deletion(-) diff --git a/versions/raml-10/raml-10.md b/versions/raml-10/raml-10.md index bff6174f..ac334c8c 100644 --- a/versions/raml-10/raml-10.md +++ b/versions/raml-10/raml-10.md @@ -461,7 +461,7 @@ All types that have the built-in object type at the root of their inheritance tr | additionalProperties? | JSON schema style syntax for declaring maps. See section [Map Types](#map-types) for more information. | patternProperties? | JSON schema style syntax for declaring key restricted maps. See section [Map Types](#map-types) for more information. | discriminator? | You may use the `discriminator` property to be able to discriminate the concrete type of an individual object at runtime when, for example, payloads contain ambiguous types (achieved via unions or inheritance). The value must correspond to a name of one of the `properties` that are defined inside a type declaration. The `discriminator` property can not be defined for inline type declarations and should only be used for scalar-valued properties. See section [Using Discriminator](#using-discriminator) for more information. -| discriminatorValue? | You may use the `discriminatorValue` property if a type also defined the `discriminator` property. The value of this property should be a valid value of the property with the name equal to the value of the `discriminator` property; and its being used to identify the declaring type. This value should be unique in the hierarchy of the type. See section [Using Discriminator](#using-discriminator) for more information.

    **Default:** the name of the type where the discriminator is applied to +| discriminatorValue? | You may use the `discriminatorValue` property if a type also defined the `discriminator` property. The value of this property should be a valid value of the property with the name equal to the value of the `discriminator` property; and its being used to identify the declaring type. This value should be unique in the hierarchy of the type. The `discriminatorValue` property can not be defined for inline type declarations. See section [Using Discriminator](#using-discriminator) for more information.

    **Default:** the name of the type where the discriminator is applied to An object type is created by explicitly inheriting from the built-in type object: @@ -733,6 +733,25 @@ data: kind: employee ``` +Neither `discriminator` nor `discriminatorValue` are allowed to be defined for any inline type declarations. + +```yaml +# valid +types: + Device: + discriminator: kind + properties: + kind: string +``` + +```yaml +# invalid +application/json: + discriminator: kind + properties: + kind: string +``` + ### Array Types Array Types are declared by using the array qualifier at the end of a Type Expression. If you are defining a top-level Array Type ( like the example below ), you can pass the following additional properties to further restrict its behavior. From 251752a27655ac1da12c26919ebb43243a855bff Mon Sep 17 00:00:00 2001 From: Christian Vogel Date: Wed, 23 Mar 2016 13:24:11 +0000 Subject: [PATCH 052/241] discriminators are also not allowed in any union types according to #307 --- versions/raml-10/raml-10.md | 13 ++++++++++--- 1 file changed, 10 insertions(+), 3 deletions(-) diff --git a/versions/raml-10/raml-10.md b/versions/raml-10/raml-10.md index ac334c8c..eeccc81e 100644 --- a/versions/raml-10/raml-10.md +++ b/versions/raml-10/raml-10.md @@ -733,10 +733,10 @@ data: kind: employee ``` -Neither `discriminator` nor `discriminatorValue` are allowed to be defined for any inline type declarations. +Neither `discriminator` nor `discriminatorValue` are allowed to be defined for any inline type declarations or union types. ```yaml -# valid +# valid when ever there is a key name that can identify a type types: Device: discriminator: kind @@ -745,13 +745,20 @@ types: ``` ```yaml -# invalid +# invalid in any inline type declarations application/json: discriminator: kind properties: kind: string ``` +```yaml +# invalid for union types +PersonOrDog: + type: Person | Dog + discriminator: hasTail +``` + ### Array Types Array Types are declared by using the array qualifier at the end of a Type Expression. If you are defining a top-level Array Type ( like the example below ), you can pass the following additional properties to further restrict its behavior. From 87a5225b0baa9fe15a6c9a355332353bb038b822 Mon Sep 17 00:00:00 2001 From: Christian Vogel Date: Thu, 24 Mar 2016 12:57:13 +0100 Subject: [PATCH 053/241] removed map types chapter in favour for a more clear additional properties section that belongs to the object type chapter; and added the changes according to issue #286 --- versions/raml-10/raml-10.md | 144 ++++++++++++++---------------------- 1 file changed, 56 insertions(+), 88 deletions(-) diff --git a/versions/raml-10/raml-10.md b/versions/raml-10/raml-10.md index 11f37e99..fa2d1af7 100644 --- a/versions/raml-10/raml-10.md +++ b/versions/raml-10/raml-10.md @@ -458,8 +458,7 @@ All types that have the built-in object type at the root of their inheritance tr | properties? | The properties that instances of this type may or must have. See section [Properties Declarations](#property-declarations) for more information. | minProperties? | The minimum number of properties allowed for instances of this type. | maxProperties? | The maximum number of properties allowed for instances of this type. -| additionalProperties? | JSON schema style syntax for declaring maps. See section [Map Types](#map-types) for more information. -| patternProperties? | JSON schema style syntax for declaring key restricted maps. See section [Map Types](#map-types) for more information. +| additionalProperties? | Boolean that indicates if an object instance has additional properties. See section [Additional Properties](#additional-properties) for more information.

    **Default:** `true` | discriminator? | Type property name to be used as discriminator, or boolean | discriminatorValue? | The value of discriminator for the type. @@ -484,6 +483,7 @@ Properties of object types are defined using the OPTIONAL **properties** propert In addition to the properties available in normal type declarations, properties can specify whether they are required and provide an optional default value. Note: + When an Object Type does not contain the "properties" property, the object is assumed to be unconstrained. That means, it may contain any properties of any type. | Property | Description | @@ -507,108 +507,87 @@ types: type: number ``` -##### Alternative Syntax +#### Additional Properties -In order to achieve a more "object oriented" experience, a series of shortcuts are available (see [Shortcuts and Syntactic Sugar](#shortcuts-and-syntactic-sugar)). The example below shows a common idiom: +By default any instance of an object can have additional properties beyond those specified in its data type `properties` node. Lets assume the following is an instance of the data type `Person` that is described in the previous section. ```yaml -#%RAML 1.0 -title: My API With Types -types: - Person: - properties: - name: string - age?: number +Person: + name: "John" + age: 35 + note: "US" # valid additional property `note` ``` -#### Inheritance +The property `note` has been not explicitly declared in the `Person` data type, but is valid based on the fact that all additional properties are by default valid. -You can declare object types that inherit from other object types: +To restrict that, one can either use the `additionalProperties` facet to not allow any additional properties by setting the value to `false`, or by specifying regular expression patterns that matches sets of keys and restricts their values: these are called "pattern properties". The patterns are delineated by pairs of opening and closing `/` characters, as follows: ```yaml #%RAML 1.0 title: My API With Types types: Person: - type: object properties: name: + required: true type: string - Employee: - type: Person - properties: - id: + age: + required: false + type: number + /^note\d+$/: # restrict any properties whose keys start with "note" + # followed by one or more digits to be a string type: string ``` -You can inherit from more than one type: +This restricts any additional properties whose keys start with "note" followed by one or more digits to be a string. Where as the example of an object instance with an additional `note` property with value "US" is valid, the following is not: ```yaml -#%RAML 1.0 -title: My API With Types -types: - Person: - type: object - properties: - name: string - EmailOwner: - type: object - properties: - email: string - Employee: - type: [ Person, EmailOwner ] - properties: - id: string +Person: + name: "John" + age: 35 + note: 123 # not valid as it is not a string + address: "US" # valid is it does not match the pattern ``` -For more details see [Object Type Inheritance](#object-type-inheritance) - -##### Map Types - -Maps (aka Dictionaries) can be declared by creating an object type and declaring a special property called "[]": +To force all additional properties to be strings, regardless of their keys, use: ```yaml #%RAML 1.0 title: My API With Types types: - MapOfNumbers: - type: object + Person: properties: - []: + name: + required: true + type: string + age: + required: false type: number + //: # force all additional properties to be a string + type: string ``` -Optionally, you can restrict the set of valid keys by specifying a regular expression within the square brackets: +If a pattern property regular expression also matches an explicitly declared property, the explicitly declared property's definition prevails. If two or more pattern property regular expressions match a property name in an instance of the data type, the first one prevails. -```yaml -#%RAML 1.0 -title: My API With Types -types: - MapOfNumbers: - type: object - properties: - [a-zA-Z]: - type: number -``` +Moreover, if `additionalProperties` is `false` (explicitly or by inheritance) in a given type definition, then pattern properties are not allowed to be set explicitly in that definition. If it is `true` (or omitted) in a given type definition, then pattern properties are allowed and further restrict the allowed additional properties in that type. + +##### Alternative Syntax -To maximize syntax compatibility with JSON Schema you can alternatively use additionalProperties and patternProperties. They will be internally rewritten +In order to achieve a more "object oriented" experience, a series of shortcuts are available (see [Shortcuts and Syntactic Sugar](#shortcuts-and-syntactic-sugar)). The example below shows a common idiom: ```yaml #%RAML 1.0 title: My API With Types - types: Person: - type: object properties: - name: - type: string - Org: - type: object - additionalProperties: Person + name: string + age?: number ``` -to +#### Inheritance + +You can declare object types that inherit from other object types: ```yaml #%RAML 1.0 @@ -619,46 +598,35 @@ types: properties: name: type: string - Org: + Employee: + type: Person properties: - []: - type: Person + id: + type: string ``` -and +You can inherit from more than one type: ```yaml #%RAML 1.0 title: My API With Types types: - Method: + Person: type: object properties: - name: - type: string - Resource: + name: string + EmailOwner: type: object - patternProperties: - "post|get|put": Method -``` - -to - -```yaml -#%RAML 1.0 -title: My API With Types -types: - Method: - type: object - properties: - name: - type: string - Resource: properties: - [post|get|put]: - type: Method + email: string + Employee: + type: [ Person, EmailOwner ] + properties: + id: string ``` +For more details see [Object Type Inheritance](#object-type-inheritance) + ### Array Types Array Types are declared by using the array qualifier at the end of a Type Expression. If you are defining a top-level Array Type ( like the example below ), you can pass the following additional properties to further restrict its behavior. From 726dbf80cfb93076463b05c1a7613dd701f14623 Mon Sep 17 00:00:00 2001 From: Christian Vogel Date: Thu, 24 Mar 2016 12:59:56 +0100 Subject: [PATCH 054/241] removed shortcut for maps --- versions/raml-10/raml-10.md | 1 - 1 file changed, 1 deletion(-) diff --git a/versions/raml-10/raml-10.md b/versions/raml-10/raml-10.md index fa2d1af7..9bf3f45e 100644 --- a/versions/raml-10/raml-10.md +++ b/versions/raml-10/raml-10.md @@ -840,7 +840,6 @@ The simplest Type Expression is just the name of a type. But Type expressions al | `string[][]` | A bi-dimensional array of string scalars | `string \| Person` | Union type made of members of string OR Person | `(string \| Person)[]` | An array of the above type -| `number{}` | A map/dictionary of numbers Type Expressions can be used wherever a Type is expected: From dc5309324b4563a4da7c3b869ba00068b5dc68cf Mon Sep 17 00:00:00 2001 From: Christian Vogel Date: Thu, 24 Mar 2016 16:52:19 +0100 Subject: [PATCH 055/241] make clear that schema and type are mutual exclusive --- versions/raml-10/raml-10.md | 20 ++++++++++++++++++++ 1 file changed, 20 insertions(+) diff --git a/versions/raml-10/raml-10.md b/versions/raml-10/raml-10.md index 9bf3f45e..5259d407 100644 --- a/versions/raml-10/raml-10.md +++ b/versions/raml-10/raml-10.md @@ -449,6 +449,26 @@ declarations may have; certain type declarations may have other properties. | description? | A longer, human-friendly description of the type | (<annotationName>)? | Annotations to be applied to this type. Annotations are any property whose key begins with "(" and ends with ")" and whose name (the part between the beginning and ending parentheses) is a declared annotation name. See section on [Annotations](#annotations) for more information. +The `schema` and `type` properties are mutually exclusive: processors MUST NOT allow both to be specified (explicitly or implicitly) inside the same type declaration. Therefore, the following examples are both invalid. + +```yaml +types: + Person: + schema: # invalid as mutually exclusive with `type` + type: # invalid as mutually exclusive with `schema` +``` + +```yaml +/resource: + get: + responses: + 200: + body: + application/json: # start type declaration + schema: # invalid as mutually exclusive with `type` + type: # invalid as mutually exclusive with `schema` +``` + ### Object Types All types that have the built-in object type at the root of their inheritance tree may use the following properties in their type declarations. From dd624617901958780391b16c8642136e3abbda5a Mon Sep 17 00:00:00 2001 From: Uri Sarid Date: Sun, 27 Mar 2016 22:46:02 -0700 Subject: [PATCH 056/241] Update raml-10.md I changed a few "may" to "MUST" --- versions/raml-10/raml-10.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/versions/raml-10/raml-10.md b/versions/raml-10/raml-10.md index 36b839b2..26b15fb5 100644 --- a/versions/raml-10/raml-10.md +++ b/versions/raml-10/raml-10.md @@ -1986,9 +1986,9 @@ A resource type is a partial resource definition that, like a resource, can spec A trait is a partial method definition that, like a method, can provide method-level properties such as description, headers, query string parameters, and responses. Methods that use one or more traits inherit those traits' properties. Resources and resource types can also use, and thus inherit from, one or more traits, which then apply to all of their methods. Traits are related to methods through a mixing pattern. -Resources may specify the resource type from which they inherit using the type property. The resource type may be the name of a resource type defined within the root-level resourceTypes property or in a library. +Resources may specify the resource type from which they inherit using the type property. The resource type MUST be the name of a resource type defined within the root-level resourceTypes property or in a library. -Similarly, methods may specify one or more traits from which they inherit using the is property. Its value is an array of traits. A resource may also use this property, in which case the array of traits is applied to all its methods. Each trait element in that array may be the name of a trait defined within the root-level traits property or in a library. +Similarly, methods may specify one or more traits from which they inherit using the is property. Its value is an array of traits. A resource may also use this property, in which case the array of traits is applied to all its methods. Each trait element in that array MUST be the name of a trait defined within the root-level traits property or in a library. Resource type definitions MUST NOT incorporate nested resources; they cannot be used to generate nested resources when they are applied to a resource, and they do not apply to its existing nested resources. From 7e808cc9b9b7547c0e3ab70a08954c31b2702eee Mon Sep 17 00:00:00 2001 From: Christian Vogel Date: Wed, 30 Mar 2016 10:11:16 +0100 Subject: [PATCH 057/241] added additional information that 'type' and 'schema' are synonymous and its recommanded to use 'type' as 'schema' is deprecated --- versions/raml-10/raml-10.md | 4 +++- 1 file changed, 3 insertions(+), 1 deletion(-) diff --git a/versions/raml-10/raml-10.md b/versions/raml-10/raml-10.md index 5259d407..3f4d4ce6 100644 --- a/versions/raml-10/raml-10.md +++ b/versions/raml-10/raml-10.md @@ -449,7 +449,7 @@ declarations may have; certain type declarations may have other properties. | description? | A longer, human-friendly description of the type | (<annotationName>)? | Annotations to be applied to this type. Annotations are any property whose key begins with "(" and ends with ")" and whose name (the part between the beginning and ending parentheses) is a declared annotation name. See section on [Annotations](#annotations) for more information. -The `schema` and `type` properties are mutually exclusive: processors MUST NOT allow both to be specified (explicitly or implicitly) inside the same type declaration. Therefore, the following examples are both invalid. +The `schema` and `type` properties are mutually exclusive and synonymous: processors MUST NOT allow both to be specified (explicitly or implicitly) inside the same type declaration. Therefore, the following examples are both invalid. ```yaml types: @@ -469,6 +469,8 @@ types: type: # invalid as mutually exclusive with `schema` ``` +It is recommended to use the `type` property instead of `schema`, as the `schema` alias is deprecated and may be removed in a future RAML version. The `type` property also allows for XML and JSON schemas. + ### Object Types All types that have the built-in object type at the root of their inheritance tree may use the following properties in their type declarations. From 99bb0d5df23ba93aea79123eeec0f82da84dcb35 Mon Sep 17 00:00:00 2001 From: Christian Vogel Date: Wed, 30 Mar 2016 10:42:39 +0100 Subject: [PATCH 058/241] improved names in the annotation target table according to #283 --- versions/raml-10/raml-10.md | 13 ++++++------- 1 file changed, 6 insertions(+), 7 deletions(-) diff --git a/versions/raml-10/raml-10.md b/versions/raml-10/raml-10.md index ff10ed1d..0b9110a0 100644 --- a/versions/raml-10/raml-10.md +++ b/versions/raml-10/raml-10.md @@ -2758,23 +2758,22 @@ The location within an API specification where annotations may be applied MUST b |Target | Description | |:--------|:------------| | API | The root of a RAML document -| DocumentationItem | An item in the collection of items that is the value of the root-level documentation property. +| DocumentationItem | An item in the collection of items that is the value of the root-level documentation property | Resource | A resource (relative URI) property, root-level or nested | Method | A method property | Response | A property of the responses property, whose key is an HTTP status code | RequestBody | The body property of a method | ResponseBody | The body property of a response | TypeDeclaration | A data type declaration (inline or in a global types collection), header declaration, query parameter declaration, or URI parameter declaration, or property within any of these declarations, where the type property may be used. -| Scalar | A scalar-valued node listed in [Annotating Scalar-valued Nodes](#scalar-valued-nodes). -| NamedExample | A property of the examples property, whose key is a name of an example and whose value describes the example. +| Example | Either an example or examples property | ResourceType | A resource type property | Trait | A trait property | SecurityScheme | A security scheme declaration | SecuritySchemeSettings | The settings property of a security scheme declaration -| AnnotationTypeDeclaration | A property of the annotationTypes property, whose key is a name of an annotation type and whose value describes the annotation. -| Library | The root of a library declaration. -| Overlay | The root of an overlay declaration. -| Extension | The root of an extension declaration. +| AnnotationType | A property of the annotationTypes property, whose key is a name of an annotation type and whose value describes the annotation. +| Library | The root of a library +| Overlay | The root of an overlay +| Extension | The root of an extension The following example illustrates applying some restrictions on the allowed targets of annotations. From 5c9bb823bf82c203ff1fa7fd900520864c4df358 Mon Sep 17 00:00:00 2001 From: Christian Vogel Date: Wed, 30 Mar 2016 11:15:45 +0100 Subject: [PATCH 059/241] removed partial method/resource text in favour for more clarity according to #304. Also moved redundant content around for a more consistent approach. --- versions/raml-10/raml-10.md | 126 +++++++++++++++++------------------- 1 file changed, 59 insertions(+), 67 deletions(-) diff --git a/versions/raml-10/raml-10.md b/versions/raml-10/raml-10.md index ff10ed1d..fd206e8e 100644 --- a/versions/raml-10/raml-10.md +++ b/versions/raml-10/raml-10.md @@ -1944,17 +1944,11 @@ There are many advantages to reusing patterns across multiple resources and meth Moreover, resource and method declarations are frequently repetitive. For example, an API that requires OAuth authentication might require an X-Access-Token header for all methods across all resources. For many reasons it may be preferable to define such a pattern in a single place and apply it consistently everywhere. -A resource type is a partial resource definition that, like a resource, can specify security schemes and methods and other properties. Resources that use a resource type inherit its properties. A resource type can also use, and thus inherit from, another resource type. Resource types and resources are related through an inheritance chain pattern. +A resource type, like a resource, can specify security schemes and methods and other properties. Resources that use a resource type inherit its properties. A resource type can also use, and thus inherit from, another resource type. Resource types and resources are related through an inheritance chain pattern. Resource type definitions MUST NOT incorporate nested resources; they cannot be used to generate nested resources when they are applied to a resource, and they do not apply to its existing nested resources. -A trait is a partial method definition that, like a method, can provide method-level properties such as description, headers, query string parameters, and responses. Methods that use one or more traits inherit those traits' properties. Resources and resource types can also use, and thus inherit from, one or more traits, which then apply to all of their methods. Traits are related to methods through a mixing pattern. +A trait, like a method, can provide method-level properties such as description, headers, query string parameters, and responses. Methods that use one or more traits inherit those traits' properties. Resources and resource types can also use, and thus inherit from, one or more traits, which then apply to all of their methods. Traits are related to methods through a mixing pattern. -Resources may specify the resource type from which they inherit using the type property. The resource type MUST be the name of a resource type defined within the root-level resourceTypes property or in a library. - -Similarly, methods may specify one or more traits from which they inherit using the is property. Its value is an array of traits. A resource may also use this property, in which case the array of traits is applied to all its methods. Each trait element in that array MUST be the name of a trait defined within the root-level traits property or in a library. - -Resource type definitions MUST NOT incorporate nested resources; they cannot be used to generate nested resources when they are applied to a resource, and they do not apply to its existing nested resources. - -### Declaration +### Declaration Resource Types and Traits Resource types may be declared via the OPTIONAL **resourceTypes** property at the root of the API definition. The value of this property is an object whose property names become names of resource types that can be referenced throughout the API, and whose property values are resource type declarations. @@ -2017,6 +2011,62 @@ resourceTypes: /groups: ``` +### Applying Resource Types and Traits + +Resources may specify the resource type from which they inherit using the OPTIONAL **type** property. The resource type MUST be the name of a resource type defined within the root-level resourceTypes property or in a library. Resource type definitions do not apply to existing nested resources. + +Similarly, methods may specify one or more traits from which they inherit using the OPTIONAL **is** property. Its value is an array of any number of elements where each MUST be the name of a trait defined within the root-level traits property or in a library. A trait may also be applied to a resource by using the **is** property, which is equivalent to applying the trait to all methods for that resource, whether declared explicitly in the resource definition or inherited from a resource type. The order of a trait getting applied to a method is from left to right; according to the traits defined in the **is** property. Trait definitions do not apply to nested resources. + +The following example illustrates the application of resource types and traits. + +```yaml +#%RAML 1.0 +title: Example API +version: v1 +resourceTypes: + collection: !include resourceTypes/collection.raml + member: !include resourceTypes/member.raml +traits: + secured: !include traits/secured.raml + paged: !include traits/paged.raml + rateLimited: !include traits/rate-limited.raml +/users: + type: collection + is: [ secured ] + get: + is: [ paged, rateLimited ] # this method is also secured + post: # this method is also secured +``` + +To pass parameter values to resource types and traits, use a map when declaring the resource type or trait to be used, as illustrated in the following example. + +```yaml +#%RAML 1.0 +title: Example API +version: v1 +resourceTypes: + searchableCollection: + get: + queryParameters: + <>: + description: Return <> that have their <> matching the given value + <>: + description: If no values match the value given for <>, use <> instead +traits: + secured: + queryParameters: + <>: + description: A valid <> is required + paged: + queryParameters: + numPages: + description: The number of pages to return, not to exceed <> +/books: + type: { searchableCollection: { queryParamName: title, fallbackParamName: digest_all_fields } } + get: + is: [ secured: { tokenName: access_token }, paged: { maxPages: 10 } ] +``` + ### Resource Type and Trait Parameters The declarations of resource types and traits MAY contain parameters, whose values MUST be specified when applying the resource type or trait, UNLESS the parameter corresponds to a reserved parameter name, in which case its value MUST be provided by the processing application. @@ -2129,64 +2179,6 @@ resourceTypes: # not required; same for the X-Chargeback header ``` -### Applying Resource Types and Traits - -The OPTIONAL **type** property applies a resource type to a resource, so that the resource inherits the resource type's characteristics. The value of the **type** property is a name of a resource type declared in the resourceTypes declaration. Resource type definitions do not apply to existing nested resources. - -The OPTIONAL **is** property applies any number of traits to a method, so that the method inherits the trait's or traits' characteristics. The value of the is attribute is an array of any number of elements, each of which is a name of a trait declared in the traits declaration. The order of a trait getting applied to a method is from left to right; according to the traits defined in the **is** property. Trait definitions do not apply to nested resources. - -A trait may also be applied to a resource by using the **is** key, which is equivalent to applying the trait to all methods for that resource, whether declared explicitly in the resource definition or inherited from a resource type. - -The following example illustrates the application of resource types and traits. - -```yaml -#%RAML 1.0 -title: Example API -version: v1 -resourceTypes: - collection: !include resourceTypes/collection.raml - member: !include resourceTypes/member.raml -traits: - secured: !include traits/secured.raml - paged: !include traits/paged.raml - rateLimited: !include traits/rate-limited.raml -/users: - type: collection - is: [ secured ] - get: - is: [ paged, rateLimited ] # this method is also secured - post: # this method is also secured -``` - -To pass parameter values to resource types and traits, use a map when declaring the resource type or trait to be used, as illustrated in the following example. - -```yaml -#%RAML 1.0 -title: Example API -version: v1 -resourceTypes: - searchableCollection: - get: - queryParameters: - <>: - description: Return <> that have their <> matching the given value - <>: - description: If no values match the value given for <>, use <> instead -traits: - secured: - queryParameters: - <>: - description: A valid <> is required - paged: - queryParameters: - numPages: - description: The number of pages to return, not to exceed <> -/books: - type: { searchableCollection: { queryParamName: title, fallbackParamName: digest_all_fields } } - get: - is: [ secured: { tokenName: access_token }, paged: { maxPages: 10 } ] -``` - ### Algorithm of Merging Traits With Methods Each RAML element has its branch of the RAML document. Informally, applying a trait to method may be described as putting traits branch under the methods branch. From 31daa9309367f4e89dbea58f3a04908ae3f92137 Mon Sep 17 00:00:00 2001 From: Christian Vogel Date: Wed, 30 Mar 2016 11:53:18 +0100 Subject: [PATCH 060/241] clarified question mark in property names --- versions/raml-10/raml-10.md | 65 +++++++++++++++++++++++++++---------- 1 file changed, 47 insertions(+), 18 deletions(-) diff --git a/versions/raml-10/raml-10.md b/versions/raml-10/raml-10.md index ff10ed1d..8f883394 100644 --- a/versions/raml-10/raml-10.md +++ b/versions/raml-10/raml-10.md @@ -504,10 +504,6 @@ Properties of object types are defined using the OPTIONAL **properties** propert In addition to the properties available in normal type declarations, properties can specify whether they are required and provide an optional default value. -Note: - -When an Object Type does not contain the "properties" property, the object is assumed to be unconstrained. That means, it may contain any properties of any type. - | Property | Description | |:----------|:----------| | default? | Provides default value for a property. @@ -529,6 +525,53 @@ types: type: number ``` +In order to achieve a more "object oriented" experience, a series of shortcuts are available (see [Shortcuts and Syntactic Sugar](#shortcuts-and-syntactic-sugar)). The example below shows a common idiom: + +```yaml +#%RAML 1.0 +title: My API With Types +types: + Person: + properties: + name: string # equals to `type: string` + age?: number # optional property; equals to `required: false` +``` + +Furthermore, when the `required` facet on a property is specified explicitly in a type declaration, any question mark in its property name is treated as part of the property name rather than as an indicator that the property is optional. + +For example, in + +```yaml +types: + profile: + properties: + preference?: + required: true +``` + +the `profile` type has a property whose name is `preference?` (including the trailing question mark) and that is required. The same property could be made optional in two equivalent ways: + +```yaml +types: + profile: + properties: + preference?: + required: false +``` + +or + +```yaml +types: + profile: + properties: + preference??: +``` + +Note: + +When an Object Type does not contain the "properties" property, the object is assumed to be unconstrained. That means, it may contain any properties of any type. + #### Additional Properties By default any instance of an object can have additional properties beyond those specified in its data type `properties` node. Lets assume the following is an instance of the data type `Person` that is described in the previous section. @@ -593,20 +636,6 @@ If a pattern property regular expression also matches an explicitly declared pro Moreover, if `additionalProperties` is `false` (explicitly or by inheritance) in a given type definition, then pattern properties are not allowed to be set explicitly in that definition. If it is `true` (or omitted) in a given type definition, then pattern properties are allowed and further restrict the allowed additional properties in that type. -##### Alternative Syntax - -In order to achieve a more "object oriented" experience, a series of shortcuts are available (see [Shortcuts and Syntactic Sugar](#shortcuts-and-syntactic-sugar)). The example below shows a common idiom: - -```yaml -#%RAML 1.0 -title: My API With Types -types: - Person: - properties: - name: string - age?: number -``` - #### Inheritance You can declare object types that inherit from other object types: From 71e28edeb40e679e18c2a855bfb3d45eb0b740c8 Mon Sep 17 00:00:00 2001 From: Christian Vogel Date: Wed, 30 Mar 2016 12:26:26 +0100 Subject: [PATCH 061/241] removed inline map type from semantic sugar section --- versions/raml-10/raml-10.md | 5 ----- 1 file changed, 5 deletions(-) diff --git a/versions/raml-10/raml-10.md b/versions/raml-10/raml-10.md index ff10ed1d..24d2af16 100644 --- a/versions/raml-10/raml-10.md +++ b/versions/raml-10/raml-10.md @@ -1319,11 +1319,6 @@ RAML Types are meant to be easy to read and write. To make the syntax more conci 
    Person:
      properties:
        nick?: string
    Person:
      type: object
      properties:
        nick:
          type: string
          required: false
    - -Inline Map -
    Person:
      properties:
        pets: Pet{}
    -
    Person:
      properties:
        pets: PetMap
    PetMap:
      properties:
        []: Pet
    - ### Inline Type Declarations From fbacee3ca391b61aa9cd58ac663a860c9e820c07 Mon Sep 17 00:00:00 2001 From: Christian Vogel Date: Thu, 31 Mar 2016 12:36:47 +0100 Subject: [PATCH 062/241] clarified rules for user defined facets and also made sure that the facets property can be applied to any type except file. --- versions/raml-10/raml-10.md | 89 +++++++++++++++---------------------- 1 file changed, 37 insertions(+), 52 deletions(-) diff --git a/versions/raml-10/raml-10.md b/versions/raml-10/raml-10.md index 8e00ef23..ce2b7635 100644 --- a/versions/raml-10/raml-10.md +++ b/versions/raml-10/raml-10.md @@ -448,6 +448,7 @@ declarations may have; certain type declarations may have other properties. | displayName? | An alternate, human-friendly name for the type | description? | A longer, human-friendly description of the type | (<annotationName>)? | Annotations to be applied to this type. Annotations are any property whose key begins with "(" and ends with ")" and whose name (the part between the beginning and ending parentheses) is a declared annotation name. See section on [Annotations](#annotations) for more information. +| facets? | A map of user defined restrictions that are being inherited by a specific sub type. See section [User defined Facets](#user-defined-facets) for more information. The `schema` and `type` properties are mutually exclusive and synonymous: processors MUST NOT allow both to be specified (explicitly or implicitly) inside the same type declaration. Therefore, the following examples are both invalid. @@ -777,18 +778,28 @@ types: ### Scalar Types -RAML provides a predefined set of Scalar Types. You can "extend" these types and add further restrictions. These restrictions are called "facets" and they exist both for scalar and object types. Each scalar type has a predefined set of facets. +RAML defines a set of built-in types and each of them has a predefined set of restrictions. All built-in types, except the file type, can declare an `enum` property. |Property Name | Description | |:--------|:------------| -| facets? | When extending from a scalar type you can define new facets (which can then be set to concrete values by subtypes). The value is an object whose properties map facets names to their types. -| enum? | Enumeration of possible values for this primitive type. Cannot be used with the file type. The value is an array containing string representations of possible values, or a single string if there is only one possible value. +| enum? | Enumeration of possible values for this built-in type. The value is an array containing string representations of possible values, or a single string if there is only one possible value. -#### Built-in Scalar Types +Example usage of enums: -RAML defines the following built-in types and additional facets. +```yaml +#%RAML 1.0 +title: My API With Types +types: + country: + type: string + enum: [ usa, rus ] -##### String + sizes: + type: number + enum: [ 1, 2, 3 ] +``` + +#### String A JSON string with the following additional facets: @@ -808,7 +819,7 @@ types: maxLength: 6 ``` -##### Number +#### Number Any JSON number including [integer](#integer) with the following additional facets: @@ -831,7 +842,7 @@ types: multipleOf: 4 ``` -##### Integer +#### Integer A subset of JSON numbers that are positive and negative multiples of 1. The integer type inherits its facets from the [number type](#number). @@ -845,7 +856,7 @@ types: multipleOf: 1 ``` -##### Boolean +#### Boolean A JSON boolean without any additional facets. @@ -855,7 +866,7 @@ types: type: boolean ``` -##### Date +#### Date The following date type representations MUST be supported: @@ -889,7 +900,7 @@ types: format: rfc2616 # this time it's required as otherwise the example is in an invalid format ``` -##### File +#### File The ​**file**​ type can be used to constrain the content to send through forms. When it is used in the context of web forms it SHOULD be represented as a valid file upload, and in JSON representation, it SHOULD be represented as a base64 encoded string with a file content. @@ -899,55 +910,29 @@ The ​**file**​ type can be used to constrain the content to send through for | minLength? | Specifies the parameter value's minimum number of bytes. Value MUST be equal or greater than 0. Defaults to 0 | maxLength? | Specifies the parameter value's maximum number of bytes. Value MUST be equal or greater than 0. Defaults to 2147483647 -#### Enums - -All custom primitive types, except for the file type, can declare an "enum" property. It should contain a set of fixed values. +### User defined Facets -Example usage of enums +RAML provides a way to also declare user defined restrictions (facets) that extend the predefined set of built-in restrictions for any scalar, array or object type. These can be defined using the `facets` property and its value is a map of user defined facets, specifically the value follows the syntax of a [property declaration](#property-declarations), that may or must be defined in any sub type that extend from the type that declares these facets. For example: ```yaml #%RAML 1.0 -title: My API With Types -types: - country: - type: string - enum: [ usa, rus ] - - sizes: - type: number - enum: [ 1, 2, 3 ] -``` - -#### Custom Scalar Types - -Defining a scalar type is similar to defining a custom object type in that you "specialize" a parent type. Here's a custom scalar type that "specializes" the number type and restricts one of its facets (minimum): - -```yaml -#%RAML 1.0 -title: My API With Types +title: API with Types types: - positiveNumber: - type: number - minimum: 1 + CustomDate: + type: date + facets: + onlyFutureDates?: boolean # optional in `PossibleMeetingDate` + noHolidays: boolean # required in `PossibleMeetingDate` + PossibleMeetingDate: + type: CustomDate + noHolidays: true ``` -For convenience, you may specialize the built-in primitive types ( string, number, etc ). However, if you don't wish your custom scalar type to inherit the predefined facets of built-in types you can inherit directly from the "scalar" type. - -You can define your own facets: - -```yaml -#%RAML 1.0 -title: My API With Types -types: - Date: - type: string - facets: - format: string +A RAML processor must follow specific rules when validating user defined facets: - MyDate: - type: Date - format: 'dd.mm.yyyy' -``` +* You can not start facet name with `(` (this is needed to avoid ambiguity with annotations). +* You can not redeclare built-in facets; for example you can not declare facet with name `properties` in any type which inherits from object type. +* You can not redeclare facets which were defined earlier in hierarchy any more. This also means that you can not inherit facets with same name from two different types. ### Type Expressions From cecf5a630d2ac29cfdd4755261c8321f2a6c6cd3 Mon Sep 17 00:00:00 2001 From: Christian Vogel Date: Thu, 31 Mar 2016 13:51:07 +0100 Subject: [PATCH 063/241] added rules for determining default types --- versions/raml-10/raml-10.md | 49 +++++++++++++++++++++++++++++++++++++ 1 file changed, 49 insertions(+) diff --git a/versions/raml-10/raml-10.md b/versions/raml-10/raml-10.md index 8e00ef23..41731246 100644 --- a/versions/raml-10/raml-10.md +++ b/versions/raml-10/raml-10.md @@ -949,6 +949,55 @@ types: format: 'dd.mm.yyyy' ``` +### Determine Default Types + +A RAML processor must be able to determine the default type of a type declaration by using the following rules: + +* If, and only if, a type declaration contains a `properties` node; the default type is `object`. For example (based on this rule): + +```yaml +types: + Person: + type: object + properties: +``` + +can also be written + +```yaml +types: + Person: + # default type is `object`, no need to explicitly define it + properties: +``` + +* If, and only if, a type declaration does not contain either a `properties` node or no explicit `type`/`schema` node; the default type is always `string`. For example (based on this rule): + +```yaml +types: + Person: + properties: + name: # no type or schema necessary since the default type is `string` +``` + +* The default type `any` is applied to any `body` node regardless if it is a response or request declaration that does not contain `properties`, `types`, or `schema`. That rule is necessary since the value of a `body` node has the same structure like a type declaration except that the key is always a media type. For example: + +```yaml +body: + application/json: # key + # default type is `any` +``` + +The last rule is important for validation purposes and needs to be defined in the specification. Of course, each rule can be overridden by explicitly define a type. For example: + +```yaml +types: + Person: + properties: + name: + type: number +``` + ### Type Expressions So far we have only used simple type identifiers to refer to other Types (ex: string, object, Person). Type Expressions provide a powerful way of referring to, and even defining, types. Type Expressions can be used wherever a type is expected. From 400c1cfba0708741fde72a556d9e1db700894d8f Mon Sep 17 00:00:00 2001 From: Christian Vogel Date: Thu, 31 Mar 2016 14:01:14 +0100 Subject: [PATCH 064/241] added an example for merging resource types --- versions/raml-10/raml-10.md | 35 +++++++++++++++++++++++++++++++++++ 1 file changed, 35 insertions(+) diff --git a/versions/raml-10/raml-10.md b/versions/raml-10/raml-10.md index 8e00ef23..545104be 100644 --- a/versions/raml-10/raml-10.md +++ b/versions/raml-10/raml-10.md @@ -2204,6 +2204,41 @@ Finally, the resource can have its own traits, and it can be applied a chain of Merging resource types with resources obeys similar rules. +The following example illustrates how a resource type gets merged into the `/products` resource. + +```yaml +resourceTypes: + collection: + get: + description: a list + headers: + APIKey: +/products: + type: collection + get: + description: override the description + responses: + 200: + body: + application/json: +``` + +The only overlay between the `collection` resource type and the resource declaration is `description` which is defined in both. In this example, the final version will have the description that has been explicitly defined in the resource. + +Every explicit node will win over the ones that are declared in a resource type or trait. The rest get's simple merged. The final merged result must be: + +```yaml +/resource: + get: + headers: + APIKey: + description: override the description + responses: + 200: + body: + application/json: +``` + ### Resource Types and Traits Effect on Collections All the collections or sequences which fall under effect of applying traits and resource types are merged. Consider an example of query parameter which has its enum values defined in both resource and trait: From 580997619fe68fe97868ff4fbb8d5421bbe00a2b Mon Sep 17 00:00:00 2001 From: Christian Vogel Date: Thu, 31 Mar 2016 15:49:16 +0100 Subject: [PATCH 065/241] added new validation chapter with a section on how to validate type instances --- versions/raml-10/raml-10.md | 95 +++++++++++++++++++++++++++++++++++-- 1 file changed, 91 insertions(+), 4 deletions(-) diff --git a/versions/raml-10/raml-10.md b/versions/raml-10/raml-10.md index 8e00ef23..53d2cd60 100644 --- a/versions/raml-10/raml-10.md +++ b/versions/raml-10/raml-10.md @@ -1273,10 +1273,6 @@ types: External types cannot participate in type inheritance or specialization. In other words: You cannot define sub-types of external types that declare new properties or set facets. You can, however, create simple type wrappers that add metadata, examples and a description. -##### Validation of instances - -Validation of instances of external types is delegated to standard json/xsd schema validation. To this end objects are automatically converted if needed to JSON or XML before validation. In the case of JSON this transformation is straightforward. In the case of XML serialization, the canonical XML serialization algorithm is used. - #### Inheritance Restrictions * You cannot inherit from types of different kind at the same moment ( kinds are: union types, array types, object types, scalar types ) @@ -1449,6 +1445,97 @@ types: value: Gold # validate against instance of the `value` property ``` +### RAML Data Type Validation + +#### Validating Type Instances + +An instance of a type passes validation if it satisfies one of the following conditions: + +1) It passes all restrictions associated with the type. + +For example, + +```yaml +types: + User: + type: object + properties: + firstName: string + lastName: string + age: + type: number + minimum: 0 +``` + +the `User` type has three properties that are required: `firstName`, `lastName`, and `age`. Each instance of this type must have these three properties defined and each value must be valid according to their individual type declaration. Therefore, the following instances are both valid: + +```yaml +User: + firstName: "John", + lastName: "Doe", + age: 35 +``` + +```yaml +User: + firstName: "John", + lastName: "Doe", + status: "single", # valid; additional properties are always allowed + age: 35 +``` + +On the other side, the example below is not valid since the `age` property has the wrong type. + +```yaml +User: + firstName: "John", + lastName: "Doe", + age: "dfgfdgsd" # not valid; it needs to be of type number +``` + +To complete the different possibilities, these are other examples that illustrate not valid type instances of the type `User` + +```yaml +User: # not valid; missing required property 'lastName' + firstName: "John", + age: 35 +``` + +```yaml +User: + firstName: "John", + lastName: "Doe", + age: -10 # not valid; minimum value for age is 0 +``` + +2) If the type is a union type then it should pass all restrictions associated with at least one of the union type options. + +```yaml +types: + CatOrDog: + type: Cat | Dog # options: Cat or Dog + Cat: + type: object + properties: + name: string + color: string + Dog: + type: object + properties: + name: string + fangs: string +``` + +A valid instance of the type `CatOrDog` for example looks like the following: + +```yaml +CatOrDog: # follows restrictions applied to the type 'Cat' + name: "Musia", + color: "brown" +``` + +3) If the type is an external type using JSON schema or XSD, a RAML processor may delegated validation to standard JSON Schema/XSD validation using third party libraries. + ### Using Types in RAML * Types may be used in several positions: From 61333d0c382d47ebdbcb13792998515c2d9404b4 Mon Sep 17 00:00:00 2001 From: Lars-Magnus Skog Date: Fri, 1 Apr 2016 00:17:40 +0200 Subject: [PATCH 066/241] remove duplicate sentence --- versions/raml-10/raml-10.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/versions/raml-10/raml-10.md b/versions/raml-10/raml-10.md index 8e00ef23..7d824d21 100644 --- a/versions/raml-10/raml-10.md +++ b/versions/raml-10/raml-10.md @@ -136,7 +136,7 @@ The following table enumerates the possible properties at the root of a RAML doc | traits? | Declarations of traits for use within this API. See section [Resource Types and Traits](#resource-types-and-traits) for more information. | resourceTypes? | Declarations of resource types for use within this API. See section [Resource Types and Traits](#resource-types-and-traits) for more information. | annotationTypes? | Declarations of annotation types for use by annotations. See section [Annotation Types](#declaring-annotation-types) for more information. -| securitySchemes? | Declarations of security schemes for use within this API. See section [Security Schemes](#security-schemes) for more information. See section [Security Schemes](#security-schemes) for more information. +| securitySchemes? | Declarations of security schemes for use within this API. See section [Security Schemes](#security-schemes) for more information. | uses? | Importing external libraries that can be used within the API. See section [Libraries](#libraries) for more information. | title | Short plain-text label for the API | version? | The version of the API, e.g. "v1" From cb7d74b7a7e858674a4a0d7adf95b723c66b2e0e Mon Sep 17 00:00:00 2001 From: Christian Vogel Date: Fri, 1 Apr 2016 17:33:09 +0100 Subject: [PATCH 067/241] moved 'default' up to type declaration and modified example to highlight the shortcut --- versions/raml-10/raml-10.md | 19 ++++++++++--------- 1 file changed, 10 insertions(+), 9 deletions(-) diff --git a/versions/raml-10/raml-10.md b/versions/raml-10/raml-10.md index 8f883394..22033633 100644 --- a/versions/raml-10/raml-10.md +++ b/versions/raml-10/raml-10.md @@ -441,6 +441,7 @@ declarations may have; certain type declarations may have other properties. | Property | Description | |:----------|:----------| +| default? | Provides a default value for a type. | schema? | Alias for the equivalent "type" property, for compatibility with RAML 0.8. Deprecated - API definitions should use the "type" property, as the "schema" alias for that property name may be removed in a future RAML version. The "type" property allows for XML and JSON schemas. | type? | A base type which the current type extends, or more generally a type expression. | example? | An example of an instance of this type. This can be used, e.g., by documentation generators to generate sample values for an object of this type. The `example` property MUST not be available when the `examples` property is already defined. @@ -502,18 +503,15 @@ types: Properties of object types are defined using the OPTIONAL **properties** property. The value of the properties property is called a "properties declaration" in this spec. It is an object whose property names specify the allowed property names of the type being declared, and whose property values are either names of types or inline type declarations. -In addition to the properties available in normal type declarations, properties can specify whether they are required and provide an optional default value. +In addition to the properties available in normal type declarations, properties can specify whether they are required or not. | Property | Description | |:----------|:----------| -| default? | Provides default value for a property. -| required? | Sets if property is optional or not. Default value is `true`. +| required? | Sets if property is optional or not.

    **Default:** `true`. The following example declares an object type with two properties: ```yaml -#%RAML 1.0 -title: My API With Types types: Person: properties: @@ -528,13 +526,16 @@ types: In order to achieve a more "object oriented" experience, a series of shortcuts are available (see [Shortcuts and Syntactic Sugar](#shortcuts-and-syntactic-sugar)). The example below shows a common idiom: ```yaml -#%RAML 1.0 -title: My API With Types types: Person: properties: - name: string # equals to `type: string` - age?: number # optional property; equals to `required: false` + name: string # equivalent to -> + # name: + # type: string + age?: number # optional property; equivalent to -> + # age: + # type: number + # required: false ``` Furthermore, when the `required` facet on a property is specified explicitly in a type declaration, any question mark in its property name is treated as part of the property name rather than as an indicator that the property is optional. From 9b8e16a065aa2d7bd6c1ec6a863d84d0df2de0b1 Mon Sep 17 00:00:00 2001 From: Christian Vogel Date: Mon, 4 Apr 2016 09:56:04 +0100 Subject: [PATCH 068/241] some fixes to spelling mistakes --- versions/raml-10/raml-10.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/versions/raml-10/raml-10.md b/versions/raml-10/raml-10.md index 545104be..f12f3edf 100644 --- a/versions/raml-10/raml-10.md +++ b/versions/raml-10/raml-10.md @@ -2223,9 +2223,9 @@ resourceTypes: application/json: ``` -The only overlay between the `collection` resource type and the resource declaration is `description` which is defined in both. In this example, the final version will have the description that has been explicitly defined in the resource. +The only overlap between the `collection` resource type and the resource declaration is `description` which is defined in both. In this example, the final version will have the description that has been explicitly defined in the resource. -Every explicit node will win over the ones that are declared in a resource type or trait. The rest get's simple merged. The final merged result must be: +Every explicit node will win over the ones that are declared in a resource type or trait. The rest is simply merged. The final merged result must be: ```yaml /resource: From 7241ebaf84084f43a40b21a2f4e5ecd2b97ee664 Mon Sep 17 00:00:00 2001 From: Christian Vogel Date: Mon, 4 Apr 2016 12:22:28 +0100 Subject: [PATCH 069/241] removed validation chapter and concentrated on making the rules more obvious inside their respective sections. --- versions/raml-10/raml-10.md | 135 +++++++++--------------------------- 1 file changed, 31 insertions(+), 104 deletions(-) diff --git a/versions/raml-10/raml-10.md b/versions/raml-10/raml-10.md index 53d2cd60..4916939c 100644 --- a/versions/raml-10/raml-10.md +++ b/versions/raml-10/raml-10.md @@ -324,15 +324,9 @@ securitySchemes: ### Introduction -RAML 1.0 introduces the notion of data **types**, which provide a concise and powerful way to describe the data in -your API. The data can be in a URI parameter (base or resource URI), a query parameter, a request or response header, -or of course a request or response body. Some types are built in, while custom types may be defined by extending -(inheriting from) the built-in types. In any place where the API expects data, a built-in type may be used to describe -the data, or a type may be extended inline to describe that data. Custom types may also be named and then used -like any built-in type. +RAML 1.0 introduces the notion of **data types**, which provide a concise and powerful way of describing the data in your API, and add rules for validating instances of data against the type declaration, so an instance is valid when it adheres to all rules for the type. The data can be in a URI parameter (base or resource URI), a query parameter, a request or response header, or of course a request or response body. Some types are built in, while custom types may be defined by extending (inheriting from) the built-in types. In any place where the API expects data, a built-in type may be used to describe the data, or a type may be extended inline to describe that data. Custom types may also be named and then used like any built-in type. -The RAML example below defines a User type with three properties: firstname and lastname of (built-in) type string, -and age of (built-in) type number. This User type is later used to describe the type (schema) for a payload. +The RAML example below defines a User type with three properties: firstname and lastname of (built-in) type string, and age of (built-in) type number. This User type is later used to describe the type (schema) for a payload. ```yaml #%RAML 1.0 @@ -353,9 +347,7 @@ types: type: User ``` -A RAML type declaration looks somewhat like a JSON schema definition. In fact, RAML types can be used instead of JSON -and XML schemas, or coexist with them. The RAML type syntax, however, is designed to be considerably easier and more -succinct than JSON and XML schemas while retaining their flexibility and expressiveness. Below is a larger example. +A RAML type declaration looks somewhat like a JSON schema definition. In fact, RAML types can be used instead of JSON and XML schemas, or coexist with them. The RAML type syntax, however, is designed to be considerably easier and more succinct than JSON and XML schemas while retaining their flexibility and expressiveness. Below is a larger example. ```yaml #%RAML 1.0 @@ -412,8 +404,7 @@ The example above contains a few advanced features. ### Overview -The RAML type system borrows from object oriented programming languages such as Java, -as well as from XSD and JSON Schemas. +The RAML type system borrows from object oriented programming languages such as Java, as well as from XSD and JSON Schemas. RAML Types in a nutshell: @@ -1089,6 +1080,32 @@ types: discriminator: kind ``` +A valid instance of a union type must pass all restrictions associated with at least one of the union type options. For example: + +```yaml +types: + CatOrDog: + type: Cat | Dog # options: Cat or Dog + Cat: + type: object + properties: + name: string + color: string + Dog: + type: object + properties: + name: string + fangs: string +``` + +A valid instance of the type `CatOrDog` for example looks like the following: + +```yaml +CatOrDog: # follows restrictions applied to the type 'Cat' + name: "Musia", + color: "brown" +``` + ### Inheritance and Specialization When declaring a RAML Type you are always inheriting from, or specializing, an existing type. The general syntax for inheritance is: @@ -1246,6 +1263,7 @@ types: type: number[] uniqueItems: true ``` + #### External Types The RAML 1.0 Type system allows seamless integration of json/xsd schemas as type definitions. This is achieved by implicitly converting references to json/xsd schemas to subtypes of the **external** built-in type. @@ -1445,97 +1463,6 @@ types: value: Gold # validate against instance of the `value` property ``` -### RAML Data Type Validation - -#### Validating Type Instances - -An instance of a type passes validation if it satisfies one of the following conditions: - -1) It passes all restrictions associated with the type. - -For example, - -```yaml -types: - User: - type: object - properties: - firstName: string - lastName: string - age: - type: number - minimum: 0 -``` - -the `User` type has three properties that are required: `firstName`, `lastName`, and `age`. Each instance of this type must have these three properties defined and each value must be valid according to their individual type declaration. Therefore, the following instances are both valid: - -```yaml -User: - firstName: "John", - lastName: "Doe", - age: 35 -``` - -```yaml -User: - firstName: "John", - lastName: "Doe", - status: "single", # valid; additional properties are always allowed - age: 35 -``` - -On the other side, the example below is not valid since the `age` property has the wrong type. - -```yaml -User: - firstName: "John", - lastName: "Doe", - age: "dfgfdgsd" # not valid; it needs to be of type number -``` - -To complete the different possibilities, these are other examples that illustrate not valid type instances of the type `User` - -```yaml -User: # not valid; missing required property 'lastName' - firstName: "John", - age: 35 -``` - -```yaml -User: - firstName: "John", - lastName: "Doe", - age: -10 # not valid; minimum value for age is 0 -``` - -2) If the type is a union type then it should pass all restrictions associated with at least one of the union type options. - -```yaml -types: - CatOrDog: - type: Cat | Dog # options: Cat or Dog - Cat: - type: object - properties: - name: string - color: string - Dog: - type: object - properties: - name: string - fangs: string -``` - -A valid instance of the type `CatOrDog` for example looks like the following: - -```yaml -CatOrDog: # follows restrictions applied to the type 'Cat' - name: "Musia", - color: "brown" -``` - -3) If the type is an external type using JSON schema or XSD, a RAML processor may delegated validation to standard JSON Schema/XSD validation using third party libraries. - ### Using Types in RAML * Types may be used in several positions: From 9af001cd640395b0481ee4556cb64264b7493a1b Mon Sep 17 00:00:00 2001 From: Christian Vogel Date: Mon, 4 Apr 2016 12:26:00 +0100 Subject: [PATCH 070/241] removed traces for discriminator inside union types --- versions/raml-10/raml-10.md | 6 ------ 1 file changed, 6 deletions(-) diff --git a/versions/raml-10/raml-10.md b/versions/raml-10/raml-10.md index 55274434..37d98df5 100644 --- a/versions/raml-10/raml-10.md +++ b/versions/raml-10/raml-10.md @@ -1088,11 +1088,6 @@ types: ### Union Types Union Types are declared using pipes (|) in your type expressions. Union Types are useful to model common scenarios in JSON based applications, for example an array containing objects which can be instances of more than one type. -If you are defining Type Alias for a Union Type ( like the example below ), you can also specify the discriminator property. See [Runtime Polymorphism (Discriminators)](#runtime-polymorphism-discriminators-). - -|Property | Description | -|:--------|:------------| -| discriminator? | Type property name to be used as a discriminator or boolean ```yaml #%RAML 1.0 @@ -1116,7 +1111,6 @@ types: kind: string Device: type: Phone | Notebook - discriminator: kind ``` ### Inheritance and Specialization From 8b12940756638f4d07fd1215626e5e455ade9a44 Mon Sep 17 00:00:00 2001 From: Christian Vogel Date: Mon, 4 Apr 2016 12:41:16 +0100 Subject: [PATCH 071/241] simplified last rule --- versions/raml-10/raml-10.md | 11 +++++++++-- 1 file changed, 9 insertions(+), 2 deletions(-) diff --git a/versions/raml-10/raml-10.md b/versions/raml-10/raml-10.md index 41731246..da39123a 100644 --- a/versions/raml-10/raml-10.md +++ b/versions/raml-10/raml-10.md @@ -980,14 +980,21 @@ types: name: # no type or schema necessary since the default type is `string` ``` -* The default type `any` is applied to any `body` node regardless if it is a response or request declaration that does not contain `properties`, `types`, or `schema`. That rule is necessary since the value of a `body` node has the same structure like a type declaration except that the key is always a media type. For example: +* The default type `any` is applied to any `body` node that does not contain `properties`, `type`, or `schema`. For example: ```yaml body: - application/json: # key + application/json: # default type is `any` ``` +Or in case that a default media type has been defined + +```yaml +body: + # default type is `any` +``` + The last rule is important for validation purposes and needs to be defined in the specification. Of course, each rule can be overridden by explicitly define a type. For example: ```yaml From bc007880323aaeabc7bcfc691f350eaafe9aea7d Mon Sep 17 00:00:00 2001 From: Christian Vogel Date: Mon, 4 Apr 2016 13:13:33 +0100 Subject: [PATCH 072/241] fixed some mistakes like built-in type -> built-in scalar type and added rule to nnot allow type instance validation against user-defined facets --- versions/raml-10/raml-10.md | 11 ++++++----- 1 file changed, 6 insertions(+), 5 deletions(-) diff --git a/versions/raml-10/raml-10.md b/versions/raml-10/raml-10.md index ce2b7635..d6db6475 100644 --- a/versions/raml-10/raml-10.md +++ b/versions/raml-10/raml-10.md @@ -778,11 +778,11 @@ types: ### Scalar Types -RAML defines a set of built-in types and each of them has a predefined set of restrictions. All built-in types, except the file type, can declare an `enum` property. +RAML defines a set of built-in scalar types and each of them has a predefined set of restrictions. All these types, except the file type, can have an additional `enum` property. |Property Name | Description | |:--------|:------------| -| enum? | Enumeration of possible values for this built-in type. The value is an array containing string representations of possible values, or a single string if there is only one possible value. +| enum? | Enumeration of possible values for this built-in scalar type. The value is an array containing string representations of possible values, or a single string if there is only one possible value. Example usage of enums: @@ -910,9 +910,9 @@ The ​**file**​ type can be used to constrain the content to send through for | minLength? | Specifies the parameter value's minimum number of bytes. Value MUST be equal or greater than 0. Defaults to 0 | maxLength? | Specifies the parameter value's maximum number of bytes. Value MUST be equal or greater than 0. Defaults to 2147483647 -### User defined Facets +### User-defined Facets -RAML provides a way to also declare user defined restrictions (facets) that extend the predefined set of built-in restrictions for any scalar, array or object type. These can be defined using the `facets` property and its value is a map of user defined facets, specifically the value follows the syntax of a [property declaration](#property-declarations), that may or must be defined in any sub type that extend from the type that declares these facets. For example: +RAML provides a way to also declare user-defined restrictions (facets) that extend the predefined set of built-in restrictions for any scalar, array or object type. These can be defined using the `facets` property and its value is a map of user defined facets, specifically the value follows the syntax of a [property declaration](#property-declarations). Depending on whether a facet is optional or required, any subtype may or must define the facets that are declared in the type it extends. For example: ```yaml #%RAML 1.0 @@ -928,11 +928,12 @@ types: noHolidays: true ``` -A RAML processor must follow specific rules when validating user defined facets: +A RAML processor must follow specific rules when validating user-defined facets: * You can not start facet name with `(` (this is needed to avoid ambiguity with annotations). * You can not redeclare built-in facets; for example you can not declare facet with name `properties` in any type which inherits from object type. * You can not redeclare facets which were defined earlier in hierarchy any more. This also means that you can not inherit facets with same name from two different types. +* You can not validate an instance of a type against user-defined facets. ### Type Expressions From 161ef8d21d0f038e9cf7fc19f5c91c3315fc01c5 Mon Sep 17 00:00:00 2001 From: Christian Vogel Date: Mon, 4 Apr 2016 13:18:37 +0100 Subject: [PATCH 073/241] remove 'uses' from any resource type or trait definition --- versions/raml-10/raml-10.md | 1 - 1 file changed, 1 deletion(-) diff --git a/versions/raml-10/raml-10.md b/versions/raml-10/raml-10.md index 37d98df5..b731ee14 100644 --- a/versions/raml-10/raml-10.md +++ b/versions/raml-10/raml-10.md @@ -1978,7 +1978,6 @@ Resource type and trait declarations can have the following properties, in addit | Property | Definition | |:---------|:-----------| | usage? | The OPTIONAL **usage** property of a resource type or trait provides instructions on how and when the resource type or trait should be used. Documentation generators MUST convey this property as characteristics of the resource and method, respectively. However, the resources and methods MUST NOT inherit the usage property: neither resources nor methods allow a property named usage. -| uses? | You may import library locally here it contents is accessible only inside of this trait The following example illustrates the declaration of several resource types and traits. From 75bcfebbf451624d6dd909b330c684cd250f4237 Mon Sep 17 00:00:00 2001 From: Christian Vogel Date: Mon, 4 Apr 2016 13:33:42 +0100 Subject: [PATCH 074/241] added additional type declaration facet 'xml' and the respective chapter --- versions/raml-10/raml-10.md | 45 +++++++++++++++++++++++++++++++++++++ 1 file changed, 45 insertions(+) diff --git a/versions/raml-10/raml-10.md b/versions/raml-10/raml-10.md index 37d98df5..92b59e86 100644 --- a/versions/raml-10/raml-10.md +++ b/versions/raml-10/raml-10.md @@ -449,6 +449,7 @@ declarations may have; certain type declarations may have other properties. | displayName? | An alternate, human-friendly name for the type | description? | A longer, human-friendly description of the type | (<annotationName>)? | Annotations to be applied to this type. Annotations are any property whose key begins with "(" and ends with ")" and whose name (the part between the beginning and ending parentheses) is a declared annotation name. See section on [Annotations](#annotations) for more information. +| xml? | The ability to configure serialization of an instance of this type into XML. See section [XML Serialization of Type Instances](#xml-serialization-of-type-instances) for more information. The `schema` and `type` properties are mutually exclusive and synonymous: processors MUST NOT allow both to be specified (explicitly or implicitly) inside the same type declaration. Therefore, the following examples are both invalid. @@ -1473,6 +1474,50 @@ types: value: Gold # validate against instance of the `value` property ``` +### XML Serialization of Type Instances + +As the serialization to XML may be a complex process, RAML introduces an additional `xml` node for [type declarations](#type-declarations) that allows to configure how type instances should be serialized to XML. The value of the `xml` node is a map that contains the following nodes. + +| Name | Type | Description | +|:---------|:------:|:-----------------| +| attribute? | `boolean` | If `attribute` is set to `true`, a type instance should be serialized as an XML attribute. It can only be `true` for scalar types.

    **Default:** `false` +| wrapped? | `boolean` | If `wrapped` is set to `true`, a type instance should be wrapped in its own XML element. It can not be `true` for scalar types and it can not be `true` at the same moment when `attribute` is `true`.

    **Default:** `false` +| name? | `string` | Allows to override the name of the XML element or XML attribute in it's XML representation.

    **Default:** the name of the type +| namespace? | `string` | Allows to configure the name of the XML namespace. +| prefix? | `string` | Allows to configure the prefix which will be used during serialization to XML. + +The following is a type declaration example that uses the `xml` node: + +```yaml +types: + Person: + properties: + name: + type: string + xml: + attribute: true # serialize it as an XML attribute + name: "fullname" # attribute should be called fullname + addresses: + type: Address[] + xml: + wrapped: true # serialize it into it's own ... XML element + Address: + properties: + street: string + city: string +``` + +The example above may be serialized into the following XML: + +```xml + + +
    …
    + ... +     +     +``` + ### Using Types in RAML * Types may be used in several positions: From 09b00755e0bb86d69fb31b03939bb0f50e3ddc5b Mon Sep 17 00:00:00 2001 From: Christian Vogel Date: Tue, 5 Apr 2016 07:27:43 +0100 Subject: [PATCH 075/241] stated more clearly how the default type string is composed and removed unnecessary sentence --- versions/raml-10/raml-10.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/versions/raml-10/raml-10.md b/versions/raml-10/raml-10.md index da39123a..520974f3 100644 --- a/versions/raml-10/raml-10.md +++ b/versions/raml-10/raml-10.md @@ -971,7 +971,7 @@ types: properties: ``` -* If, and only if, a type declaration does not contain either a `properties` node or no explicit `type`/`schema` node; the default type is always `string`. For example (based on this rule): +* If, and only if, a type declaration contains neither a `properties` node nor a `type` or `schema` node, then the default type is `string`. For example (based on this rule): ```yaml types: @@ -995,7 +995,7 @@ body: # default type is `any` ``` -The last rule is important for validation purposes and needs to be defined in the specification. Of course, each rule can be overridden by explicitly define a type. For example: +Of course, each rule can be overridden by explicitly define a type. For example: ```yaml types: From 44f4fe185f28577a3279e3299a2342fef1f874f9 Mon Sep 17 00:00:00 2001 From: Kris Hahn Date: Mon, 4 Apr 2016 23:39:25 -0700 Subject: [PATCH 076/241] update raml-10.md for RC2 wordsmithing abstract section --- versions/raml-10/raml-10.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/versions/raml-10/raml-10.md b/versions/raml-10/raml-10.md index 26ae4f9f..cb96b5c2 100644 --- a/versions/raml-10/raml-10.md +++ b/versions/raml-10/raml-10.md @@ -2,7 +2,7 @@ ## Abstract -RAML is a language for the definition of HTTP-based APIs that embody most or all of the principles of Representational State Transfer (REST). The RAML specification (this document) defines an application of the [YAML 1.2 specification](http://yaml.org/spec/1.2/spec.html) that provides mechanisms for the definition of practically-RESTful APIs while providing provisions with which source code generators for client and server source code and comprehensive user documentation can be created. +RAML is a language for the definition of HTTP-based APIs that embody most or all of the principles of Representational State Transfer (REST). This document constitutes the RAML specification, an application of the [YAML 1.2 specification](http://yaml.org/spec/1.2/spec.html). The RAML specification provides mechanisms for defining practically-RESTful APIs, creating client/server source code, and comprehensively documenting the APIs for users. ## Status of this Document From 65ddc39a8eda928e6f507900928694e6c712fc8b Mon Sep 17 00:00:00 2001 From: Christian Vogel Date: Wed, 6 Apr 2016 08:50:53 +0100 Subject: [PATCH 077/241] clarified the value of the 'type' node --- versions/raml-10/raml-10.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/versions/raml-10/raml-10.md b/versions/raml-10/raml-10.md index cb96b5c2..02ce68b9 100644 --- a/versions/raml-10/raml-10.md +++ b/versions/raml-10/raml-10.md @@ -434,7 +434,7 @@ declarations may have; certain type declarations may have other properties. |:----------|:----------| | default? | Provides a default value for a type. | schema? | Alias for the equivalent "type" property, for compatibility with RAML 0.8. Deprecated - API definitions should use the "type" property, as the "schema" alias for that property name may be removed in a future RAML version. The "type" property allows for XML and JSON schemas. -| type? | A base type which the current type extends, or more generally a type expression. +| type? | A base type which the current type extends, or more generally a type expression. The value of a type node must be the name of either a user-defined type or one of the built-in types (object, array, or a scalar type), or a JSON or XML Schema. | example? | An example of an instance of this type. This can be used, e.g., by documentation generators to generate sample values for an object of this type. The `example` property MUST not be available when the `examples` property is already defined. | examples? | An object containing named examples of instances of this type. This can be used, e.g., by documentation generators to generate sample values for an object of this type. The `examples` property MUST not be available when the `example` property is already defined. See section [Examples](#defining-examples-in-raml) for more information. | displayName? | An alternate, human-friendly name for the type From 31a0faddc066fad2d978653916f8cfeb6a5c9175 Mon Sep 17 00:00:00 2001 From: Christian Vogel Date: Wed, 6 Apr 2016 08:59:38 +0100 Subject: [PATCH 078/241] clarified the value of the 'types' node --- versions/raml-10/raml-10.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/versions/raml-10/raml-10.md b/versions/raml-10/raml-10.md index cb96b5c2..34d41e20 100644 --- a/versions/raml-10/raml-10.md +++ b/versions/raml-10/raml-10.md @@ -132,7 +132,7 @@ The following table enumerates the possible properties at the root of a RAML doc | description? | A longer, human-friendly description of the API | (<annotationName>)? | Annotations to be applied to this API. Annotations are any property whose key begins with "(" and ends with ")" and whose name (the part between the beginning and ending parentheses) is a declared annotation name. See section [Annotations](#annotations) for more information. | schemas? | Alias for the equivalent "types" property, for compatibility with RAML 0.8. Deprecated - API definitions should use the "types" property, as the "schemas" alias for that property name may be removed in a future RAML version. The "types" property allows for XML and JSON schemas. -| types? | Declarations of (data) types for use within this API. See section [RAML Data Types](#raml-data-types) for more information. +| types? | Declarations of (data) types for use within this API. The value is a map where each key represents the name of the type and the value a type declaration. See section [RAML Data Types](#raml-data-types) for more information. | traits? | Declarations of traits for use within this API. See section [Resource Types and Traits](#resource-types-and-traits) for more information. | resourceTypes? | Declarations of resource types for use within this API. See section [Resource Types and Traits](#resource-types-and-traits) for more information. | annotationTypes? | Declarations of annotation types for use by annotations. See section [Annotation Types](#declaring-annotation-types) for more information. From 9f83769568abc4fa102dc22957bf4f6b440336d1 Mon Sep 17 00:00:00 2001 From: Christian Vogel Date: Wed, 6 Apr 2016 18:51:11 +0100 Subject: [PATCH 079/241] added security scheme as possible fragment --- versions/raml-10/raml-10.md | 1 + 1 file changed, 1 insertion(+) diff --git a/versions/raml-10/raml-10.md b/versions/raml-10/raml-10.md index cb96b5c2..695d89d4 100644 --- a/versions/raml-10/raml-10.md +++ b/versions/raml-10/raml-10.md @@ -3012,6 +3012,7 @@ A file to be included MAY begin with a RAML fragment identifier line, which cons | Library | A RAML library; see the section on [Libraries](#libraries). | Overlay | An overlay file; see the section on [Overlays](#overlays). | Extension | An extension file; see the section on [Extensions](#extensions). +| SecurityScheme | A definition of a security scheme; see section on [Security Schemes](#security-schemes) If a file begins with a RAML fragment identifier line, and the fragment identifier is neither Library nor Overlay nor Extension, the contents of the file after removal of the RAML fragment identifier line MUST be valid structurally according to the corresponding section of this RAML specification. For example, a RAML file beginning with `#%RAML 1.0 Trait` must have the structure of a RAML trait declaration as defined in the [specification for traits](#resource-types-and-traits), such that including the file in a location where a trait declaration is called for results in a valid RAML file. From 4f7bcc4f89ee11f88c434d9e8fbf3262377fc3bc Mon Sep 17 00:00:00 2001 From: Christian Vogel Date: Thu, 7 Apr 2016 14:14:04 +0100 Subject: [PATCH 080/241] full re-work of the 'External Types' chapter --- versions/raml-10/raml-10.md | 120 ++++++++++++++++++++++++++++-------- 1 file changed, 93 insertions(+), 27 deletions(-) diff --git a/versions/raml-10/raml-10.md b/versions/raml-10/raml-10.md index 695d89d4..27f91763 100644 --- a/versions/raml-10/raml-10.md +++ b/versions/raml-10/raml-10.md @@ -1187,6 +1187,99 @@ CatOrDog: # follows restrictions applied to the type 'Cat' color: "brown" ``` +### Using XML and JSON Schema + +RAML allows to not only define data using the type system, although it is recommended, but also provides mechanism to define them in XML and/or JSON schemas. + +A RAML Processor MUST be able to interpret JSON Schema and XML Schema. + +#### Schemas Node + +The root-level **schemas** node specifies a map of schemas that could be used anywhere in the API definition. The value of the **schemas** node is a map; in which each key is the schema name, and the values are [schema definitions](#schema-node). The schema definitions MAY be included inline or by using `!include`. + +The following example shows how to define a global definition that includes an external file which contains the schema. + +```yaml +schemas: + Person: !include person.json +``` + +Please note that "schemas" is an alias for the equivalent "types" node, for compatibility with RAML 0.8 and is deprecated. API definitions should use the "types" node, as the "schemas" alias may be removed in a future RAML version. The "types" node also allows for XML and JSON schemas (see [Using RAML Data Type System](#using-raml-data-type-system)). + +#### Schema Node + +The **schema** node specifies a schema that MAY be declared inline or in an external file. Alternatively, the value of the **schema** node MAY be the name of a schema specified in the root-level **schemas** node. If the schema is sufficiently large so as to make it difficult for a person to read the API definition, or the schema is reused across multiple APIs or across multiple miles in the same API, an external file SHOULD be used instead of including the content inline. + +This example shows a schema declaration for both; inline and included from an external file. + +```yaml +/person: + get: + responses: + 200: + body: + application/json: + schema: | + { + "title": "Example Schema", + "type": "object", + "properties": { + "firstName": { + "type": "string" + }, + "lastName": { + "type": "string" + }, + "age": { + "description": "Age in years", + "type": "integer", + "minimum": 0 + } + } + } + post: + body: + application/json: + schema: !include person.json +``` + +The **schema** node CANNOT be specified if a body's media type is application/x-www-form-urlencoded or multipart/form-data, or if a "type" node has been specified already (see [Using RAML Data Type System](#using-raml-data-type-system)). + +Please note that "schema" is an alias for the equivalent "type" node, for compatibility with RAML 0.8 and is deprecated. API definitions should use the "type" node, as the "schema" alias may be removed in a future RAML version. The "type" node allows for XML and JSON schemas (see [Using RAML Data Type System](#using-raml-data-type-system)). + +#### Using RAML Data Type System + +RAML's type system allows seamless integration of JSON and XML schemas as type definitions. That follows the same rules as using **schemas** or **schema**. Both are synonymous to **types** and **type**, with the restriction that **type** and **schema** are mutually exclusive. + +The following examples show how to include an external JSON schema into a root-level type definition and a body declaration. + +```yaml +types: + Person: !include person.json +``` + +```yaml +/person: + get: + responses: + 200: + body: + application/json: + type: !include person.json +``` + +A RAML processor MUST not allow types that define an XML or JSON schema to participate in type inheritance or specialization. In other words: You cannot define sub-types of external types that declare new properties or set facets. You can, however, create simple type wrappers that add metadata, examples and a description. + +This example shows an invalid case where a type inherits the characteristics of a JSON schema and adds additional properties. + +```yaml +types: + Person: + type: !include person.json + properties: # invalid + single: boolean +``` + ### Inheritance and Specialization When declaring a RAML Type you are always inheriting from, or specializing, an existing type. The general syntax for inheritance is: @@ -1345,33 +1438,6 @@ types: uniqueItems: true ``` -#### External Types - -The RAML 1.0 Type system allows seamless integration of json/xsd schemas as type definitions. This is achieved by implicitly converting references to json/xsd schemas to subtypes of the **external** built-in type. - -These types can then be used freely within the RAML Type system as normal types except for one restriction: You cannot inherit from them. - -The following type declarations create subclasses of external types. - -```yaml -#%RAML 1.0 -title: My API With Types -types: - Person: - type: !include schemas/PersonSchema.json -``` - -```yaml -#%RAML 1.0 -title: My API With Types -types: - Person: !include schemas/PersonSchema.xsd -``` - -##### External Types and Inheritance - -External types cannot participate in type inheritance or specialization. In other words: You cannot define sub-types of external types that declare new properties or set facets. You can, however, create simple type wrappers that add metadata, examples and a description. - #### Inheritance Restrictions * You cannot inherit from types of different kind at the same moment ( kinds are: union types, array types, object types, scalar types ) From 9f2be2406f65707dcd79e9bc87f8805686d652ef Mon Sep 17 00:00:00 2001 From: Christian Vogel Date: Thu, 7 Apr 2016 14:44:01 +0100 Subject: [PATCH 081/241] added a bit more clarity around restrictions using XML/JSON schemas with type system --- versions/raml-10/raml-10.md | 13 +++++++++++-- 1 file changed, 11 insertions(+), 2 deletions(-) diff --git a/versions/raml-10/raml-10.md b/versions/raml-10/raml-10.md index 27f91763..3ffc3e74 100644 --- a/versions/raml-10/raml-10.md +++ b/versions/raml-10/raml-10.md @@ -1268,9 +1268,18 @@ types: type: !include person.json ``` -A RAML processor MUST not allow types that define an XML or JSON schema to participate in type inheritance or specialization. In other words: You cannot define sub-types of external types that declare new properties or set facets. You can, however, create simple type wrappers that add metadata, examples and a description. +A RAML processor MUST not allow types that define an XML or JSON schema to participate in type inheritance or specialization. In other words: You cannot define sub-types of these types that declare new properties, add restrictions, and set or declare facets. You can, however, create simple type wrappers that add annotations, examples or a description. -This example shows an invalid case where a type inherits the characteristics of a JSON schema and adds additional properties. +The following is a fully valid example. + +```yaml +types: + Person: + type: !include person.json + description: this is a schema describing person +``` + +However, this example shows an invalid case where a type inherits the characteristics of a JSON schema and adds additional properties. ```yaml types: From b515b4ccd9192aa9c814c648ed678bdec9d2b209 Mon Sep 17 00:00:00 2001 From: Christian Vogel Date: Thu, 7 Apr 2016 18:26:03 +0100 Subject: [PATCH 082/241] changed content of the 'queryString' description to make more explicit what the values are --- versions/raml-10/raml-10.md | 43 +++++++++++++++++++++++++++++++------ 1 file changed, 36 insertions(+), 7 deletions(-) diff --git a/versions/raml-10/raml-10.md b/versions/raml-10/raml-10.md index 695d89d4..3038f007 100644 --- a/versions/raml-10/raml-10.md +++ b/versions/raml-10/raml-10.md @@ -1904,20 +1904,49 @@ An API's methods may support or require a query string in the URL on which they #### The Query String as a Whole -The queryString property is used to specify the query string as a whole, rather than as name-value pairs. Its value is either the name of a type or an inline type declaration. +The queryString property is used to specify the query string as a whole, rather than as name-value pairs. Its value is either the name of a type, including union types; or an inline type declaration. The type must be derived from a scalar type or from an object type. -If the queryString property specifies a non-scalar type or a union of non-scalar types, then processors MUST default to treating the format of the query string as JSON in applying the type to instances of that query string. They MAY allow other treatments based on annotations. +If the type is derived from a scalar type, the query string as a whole MUST be described by the type. -The following example shows a get method with a query string that is expected to be in JSON format. +If the type is derived from an object type, processors MUST regard the query string as a URL-encoded serialization of an instance of this object type; that is, the query string must be of the form "parameter1=value1¶meter2=value2&..." where "parameter1", "parameter2", etc. correspond to the properties in the object type, and the values to the corresponding value specifications in the object type. If a value of a property in the object type is an array type, processors MUST interpret this as allowing multiple instances of that query parameter in the query string. In such a case, the underlying type of the array -- namely, the type of the elements of the array -- MUST be applied as the type of the value of instances of this query parameter. + +In the following example, union types and extending from multiple types are used to constrain the query parameters to specific alternatives: ```yaml #%RAML 1.0 -title: Example with query string -/users: +title: Illustrate query parameter variations +types: + lat-long: # lat & long required; mutually exclusive with location + properties: + lat: number + long: number + loc: # location required; mutually exclusive with lat & long + properties: + location: + paging: # each is optional, not exclusive with anything + properties: + start?: number + page-size?: number +/locations: get: queryString: - description: We filter based on a JSON-formatted query string - type: !include schemas/usersFilter.json + type: [paging, lat-long | loc ] + examples: + first: + content: + start: 2 + lat: 12 + long: 13 + second: + content: + start: 2 + page-size: 20 + location: 1,2 + third: # not valid + content: + lat: 12 + location: 2 + strict: false # because it's not valid ``` #### Query Parameters in a Query String From 1609d987529074f4b0ee30a984a06a52119e5dab Mon Sep 17 00:00:00 2001 From: Christian Vogel Date: Thu, 7 Apr 2016 18:37:30 +0100 Subject: [PATCH 083/241] made it a bit clearer what a processor might do validating an instance against user-defined facets; and also added that they are not inherited --- versions/raml-10/raml-10.md | 2 ++ 1 file changed, 2 insertions(+) diff --git a/versions/raml-10/raml-10.md b/versions/raml-10/raml-10.md index 60cd8153..89f115a3 100644 --- a/versions/raml-10/raml-10.md +++ b/versions/raml-10/raml-10.md @@ -956,6 +956,8 @@ A RAML processor must follow specific rules when validating user-defined facets: * You can not redeclare built-in facets; for example you can not declare facet with name `properties` in any type which inherits from object type. * You can not redeclare facets which has been defined in a super type. This also means that you can not inherit facets with the same name from two different types. * You can not validate an instance of a type against user-defined facets. +* A RAML processors MAY be not required to validate an instance of a type against user-defined facets. +* A sub-type does not automatically inherit the user-defined facets from its parent type; hence a type that extends from `PossibleMeetingDate` must not define any of the user-defined facets that are part of `CustomDate`. ### Determine Default Types From 52d31e8edbedc228d882d8650d9f5ad2e3f30c41 Mon Sep 17 00:00:00 2001 From: Christian Vogel Date: Thu, 7 Apr 2016 18:55:04 +0100 Subject: [PATCH 084/241] made more explicit that RAML does not allow multiple paths to be resolved into the same --- versions/raml-10/raml-10.md | 20 ++++++++++++++++++++ 1 file changed, 20 insertions(+) diff --git a/versions/raml-10/raml-10.md b/versions/raml-10/raml-10.md index 695d89d4..48e4f05d 100644 --- a/versions/raml-10/raml-10.md +++ b/versions/raml-10/raml-10.md @@ -1671,6 +1671,26 @@ https://api.github.com/users/{userId}/keys https://api.github.com/users/{userId}/keys/{keyId} ``` +A RAML processor MUST not allow a fully-combined path, which you get from combining the resource's path with all of its parents, to be identical to another fully-combined path, WITHOUT consideration to the possible values of any URI parameter. + +This example would be FORBIDDEN. + +```yaml +/users: + /foo: +/users/foo: +``` + +(both paths combine to the same `/users/foo`), and on the other hand this would ALWAYS be ALLOWED. + +```yaml +/users/{userId}: +/users/{username}: +/users/me: +``` + +### Resource Property + The value of a resource property is an object whose properties are described in the following table. |Property | Description | From 30634038301e37f7b12c51716a62f0f55589db4c Mon Sep 17 00:00:00 2001 From: Christian Vogel Date: Fri, 8 Apr 2016 13:54:31 +0100 Subject: [PATCH 085/241] added more clarity about the array type --- versions/raml-10/raml-10.md | 24 ++++++++++++++++++++---- 1 file changed, 20 insertions(+), 4 deletions(-) diff --git a/versions/raml-10/raml-10.md b/versions/raml-10/raml-10.md index 695d89d4..1305e7dc 100644 --- a/versions/raml-10/raml-10.md +++ b/versions/raml-10/raml-10.md @@ -773,7 +773,7 @@ PersonOrDog: ### Array Types -Array Types are declared by using the array qualifier at the end of a Type Expression. If you are defining a top-level Array Type ( like the example below ), you can pass the following additional properties to further restrict its behavior. +Array Types are declared by either using the array qualifier `[]` at the end of a [type expression](#type-expressions) or `array` as the value of a `type` node. If you are defining a top-level array type (like the example below), you can pass the following additional properties to further restrict its behavior. | Property | Description | |:----------|:----------| @@ -782,21 +782,37 @@ Array Types are declared by using the array qualifier at the end of a Type Expre | minItems? | Minimum amount of items in array. Value MUST be equal or greater than 0. Defaults to 0. | maxItems? | Maximum amount of items in array. Value MUST be equal or greater than 0. Defaults to 2147483647. +So following are both valid examples: + ```yaml -#%RAML 1.0 -title: My API With Types types: Email: type: object properties: name: type: string - emails: + Emails: type: Email[] minItems: 1 uniqueItems: true ``` +```yaml +types: + Email: + type: object + properties: + name: + type: string + Emails: + type: array + items: Email + minItems: 1 + uniqueItems: true +``` + +Using `Email[]` is equivalent to use `type: array` and specifically define the type each items in the array inherit from using the `items` facet. + ### Scalar Types RAML provides a predefined set of Scalar Types. You can "extend" these types and add further restrictions. These restrictions are called "facets" and they exist both for scalar and object types. Each scalar type has a predefined set of facets. From 2da93e09120d5be5808c9b25ffef415de6dcf370 Mon Sep 17 00:00:00 2001 From: Christian Vogel Date: Tue, 12 Apr 2016 08:29:47 +0100 Subject: [PATCH 086/241] transformed bullet points into a more clear text --- versions/raml-10/raml-10.md | 16 +++++++++++++--- 1 file changed, 13 insertions(+), 3 deletions(-) diff --git a/versions/raml-10/raml-10.md b/versions/raml-10/raml-10.md index 89f115a3..c703fdad 100644 --- a/versions/raml-10/raml-10.md +++ b/versions/raml-10/raml-10.md @@ -934,7 +934,15 @@ The ​**file**​ type can be used to constrain the content to send through for ### User-defined Facets -RAML provides a way to also declare user-defined restrictions (facets) that extend the predefined set of built-in restrictions for any scalar, array or object type. These can be defined using the `facets` property and its value is a map of user defined facets, specifically the value follows the syntax of a [property declaration](#property-declarations). Depending on whether a facet is optional or required, any subtype may or must define the facets that are declared in the type it extends. For example: +Facets express various additional restrictions which types impose on their instances, such as the optional `minimum` and `maximum` facets for numbers, or the `enum` facet for scalars. RAML provides a way to declare additional user-defined facets for any data type. + +User-defined facets are defined using the OPTIONAL `facets` property on a type declaration. Its value is a map whose keys name the user-defined facets and whose corresponding values define the concrete values which the corresponding facet may take, following the same syntax as [property declaration](#property-declarations). That is, a facet declaration in the declaration of a type specifies the concrete values which subtypes may use for that facet to restrict instances of those subtypes. Note that this implies that user-defined facets on a type do not restrict instances of that type but rather only instances of subtypes of that type. + +Facet names MUST NOT begin with open parentheses, to disambiguate them from annotations. User-defined facet names on a type MUST NOT match built-in facets on that type, nor facet names of any ancestor type in the type's inheritance chain. + +If a facet of a type is declared as required, then any subtype of that type MUST define a value for that facet. + +Here is an example which defines the capability to add restrictions on dates that indicate they may not fall on holidays: ```yaml #%RAML 1.0 @@ -950,13 +958,15 @@ types: noHolidays: true ``` +In the above example, the possibility of restricting date instances based on whether they fall on holidays is introduced by declaring the `noHolidays` facet and defining its values to be boolean. Then instances of any inheriting type, such as the `PossibleMeetingDate` type, must have values that do not fall on holidays. + +Because user-defined facets are by definition not built into this RAML specification, and hence their semantic may not be understood by all RAML processors, a RAML processor may or may not choose to use user-defined facets on a type in validating instances of that type. In the example above, a RAML processor may or may not assign a meaning to `noHolidays` and so may choose to ignore the `noHolidays: true` value in validating instances of `PossibleMeetingDate`. + A RAML processor must follow specific rules when validating user-defined facets: * You can not start facet name with `(` (this is needed to avoid ambiguity with annotations). * You can not redeclare built-in facets; for example you can not declare facet with name `properties` in any type which inherits from object type. * You can not redeclare facets which has been defined in a super type. This also means that you can not inherit facets with the same name from two different types. -* You can not validate an instance of a type against user-defined facets. -* A RAML processors MAY be not required to validate an instance of a type against user-defined facets. * A sub-type does not automatically inherit the user-defined facets from its parent type; hence a type that extends from `PossibleMeetingDate` must not define any of the user-defined facets that are part of `CustomDate`. ### Determine Default Types From 2df2dfdfaf57ed652c90c3fd9c08a71f1d3eed20 Mon Sep 17 00:00:00 2001 From: Christian Vogel Date: Tue, 12 Apr 2016 09:14:25 +0100 Subject: [PATCH 087/241] adjusted the paragraph to link back to the computation of absolute URIs --- versions/raml-10/raml-10.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/versions/raml-10/raml-10.md b/versions/raml-10/raml-10.md index 48e4f05d..8001c15d 100644 --- a/versions/raml-10/raml-10.md +++ b/versions/raml-10/raml-10.md @@ -1622,7 +1622,7 @@ baseUri: https://api.github.com The key of a resource property, i.e. its relative URI, MAY consist of multiple URI path fragments separated by slashes; e.g. /bom/items may indicate the collection of items in a bill of materials as a single resource. However, if the individual URI path fragments are themselves resources, the API definition SHOULD use nested resources to describe this structure; e.g. if /bom is itself a resource then /items should be a nested resource of /bom, vs using /bom/items as a non-nested resource. -Absolute URIs are not explicitly specified. They are computed by starting with the baseUri and appending the relative URI of the top-level resource, and then successively appending the relative URI values for each nested resource until the target resource is reached. +Absolute URIs are not explicitly specified. They are computed by appending the relative URI of the top-level resource, and then successively appending the relative URI values for each nested resource until the target resource is reached. If, and only if, a baseUri has been defined, each relative URI of the top-level resource needs to start with the base URI. Taking the previous example, the absolute URI of the public gists resource is formed as follows. @@ -1671,7 +1671,7 @@ https://api.github.com/users/{userId}/keys https://api.github.com/users/{userId}/keys/{keyId} ``` -A RAML processor MUST not allow a fully-combined path, which you get from combining the resource's path with all of its parents, to be identical to another fully-combined path, WITHOUT consideration to the possible values of any URI parameter. +A RAML processor MUST NOT allow one of the computed absolute URIs to be identical to another one, WITHOUT consideration to the possible values of any URI parameter. This example would be FORBIDDEN. From 32652698c8638b22e202cfa6cd101e8e291f96c8 Mon Sep 17 00:00:00 2001 From: Christian Vogel Date: Tue, 12 Apr 2016 09:18:40 +0100 Subject: [PATCH 088/241] applied last comment to make the different value types more clear --- versions/raml-10/raml-10.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/versions/raml-10/raml-10.md b/versions/raml-10/raml-10.md index 3038f007..550689f8 100644 --- a/versions/raml-10/raml-10.md +++ b/versions/raml-10/raml-10.md @@ -1904,7 +1904,7 @@ An API's methods may support or require a query string in the URL on which they #### The Query String as a Whole -The queryString property is used to specify the query string as a whole, rather than as name-value pairs. Its value is either the name of a type, including union types; or an inline type declaration. The type must be derived from a scalar type or from an object type. +The queryString property is used to specify the query string as a whole, rather than as name-value pairs. Its value is either the name of a data type or an inline data type declaration (including a data type expression). In either case the types at the root of the type hierarchy of the data type MUST all be either a scalar type or the object type, after fully expanding any union type expressions at every level of the type hierarchy. If the type is derived from a scalar type, the query string as a whole MUST be described by the type. From 39c40cef5d0131866cdaa32fb4ab6052e95ebbe4 Mon Sep 17 00:00:00 2001 From: Christian Vogel Date: Tue, 12 Apr 2016 09:49:28 +0100 Subject: [PATCH 089/241] removed all rules since they are in the description text --- versions/raml-10/raml-10.md | 7 ------- 1 file changed, 7 deletions(-) diff --git a/versions/raml-10/raml-10.md b/versions/raml-10/raml-10.md index c703fdad..91293f2f 100644 --- a/versions/raml-10/raml-10.md +++ b/versions/raml-10/raml-10.md @@ -962,13 +962,6 @@ In the above example, the possibility of restricting date instances based on whe Because user-defined facets are by definition not built into this RAML specification, and hence their semantic may not be understood by all RAML processors, a RAML processor may or may not choose to use user-defined facets on a type in validating instances of that type. In the example above, a RAML processor may or may not assign a meaning to `noHolidays` and so may choose to ignore the `noHolidays: true` value in validating instances of `PossibleMeetingDate`. -A RAML processor must follow specific rules when validating user-defined facets: - -* You can not start facet name with `(` (this is needed to avoid ambiguity with annotations). -* You can not redeclare built-in facets; for example you can not declare facet with name `properties` in any type which inherits from object type. -* You can not redeclare facets which has been defined in a super type. This also means that you can not inherit facets with the same name from two different types. -* A sub-type does not automatically inherit the user-defined facets from its parent type; hence a type that extends from `PossibleMeetingDate` must not define any of the user-defined facets that are part of `CustomDate`. - ### Determine Default Types A RAML processor must be able to determine the default type of a type declaration by using the following rules: From b46075dcee60d0320a68a2f0c7da220bd93cffbe Mon Sep 17 00:00:00 2001 From: Christian Vogel Date: Wed, 13 Apr 2016 08:08:37 +0100 Subject: [PATCH 090/241] fixed example from using 'type' facet instead of 'schema' --- versions/raml-10/raml-10.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/versions/raml-10/raml-10.md b/versions/raml-10/raml-10.md index 954e43ea..912e6063 100644 --- a/versions/raml-10/raml-10.md +++ b/versions/raml-10/raml-10.md @@ -389,7 +389,7 @@ types: 200: body: application/json: - schema: Org + type: Org ``` The example above contains a few advanced features. From eb6810d6ba3a227c9730525a78f02137e9773b74 Mon Sep 17 00:00:00 2001 From: Christian Vogel Date: Wed, 13 Apr 2016 13:25:24 +0100 Subject: [PATCH 091/241] modified chapter to make it more concise and obvious that it is recommended to use types and type --- versions/raml-10/raml-10.md | 66 +++---------------------------------- 1 file changed, 5 insertions(+), 61 deletions(-) diff --git a/versions/raml-10/raml-10.md b/versions/raml-10/raml-10.md index 3ffc3e74..0fe06dc0 100644 --- a/versions/raml-10/raml-10.md +++ b/versions/raml-10/raml-10.md @@ -1189,67 +1189,7 @@ CatOrDog: # follows restrictions applied to the type 'Cat' ### Using XML and JSON Schema -RAML allows to not only define data using the type system, although it is recommended, but also provides mechanism to define them in XML and/or JSON schemas. - -A RAML Processor MUST be able to interpret JSON Schema and XML Schema. - -#### Schemas Node - -The root-level **schemas** node specifies a map of schemas that could be used anywhere in the API definition. The value of the **schemas** node is a map; in which each key is the schema name, and the values are [schema definitions](#schema-node). The schema definitions MAY be included inline or by using `!include`. - -The following example shows how to define a global definition that includes an external file which contains the schema. - -```yaml -schemas: - Person: !include person.json -``` - -Please note that "schemas" is an alias for the equivalent "types" node, for compatibility with RAML 0.8 and is deprecated. API definitions should use the "types" node, as the "schemas" alias may be removed in a future RAML version. The "types" node also allows for XML and JSON schemas (see [Using RAML Data Type System](#using-raml-data-type-system)). - -#### Schema Node - -The **schema** node specifies a schema that MAY be declared inline or in an external file. Alternatively, the value of the **schema** node MAY be the name of a schema specified in the root-level **schemas** node. If the schema is sufficiently large so as to make it difficult for a person to read the API definition, or the schema is reused across multiple APIs or across multiple miles in the same API, an external file SHOULD be used instead of including the content inline. - -This example shows a schema declaration for both; inline and included from an external file. - -```yaml -/person: - get: - responses: - 200: - body: - application/json: - schema: | - { - "title": "Example Schema", - "type": "object", - "properties": { - "firstName": { - "type": "string" - }, - "lastName": { - "type": "string" - }, - "age": { - "description": "Age in years", - "type": "integer", - "minimum": 0 - } - } - } - post: - body: - application/json: - schema: !include person.json -``` - -The **schema** node CANNOT be specified if a body's media type is application/x-www-form-urlencoded or multipart/form-data, or if a "type" node has been specified already (see [Using RAML Data Type System](#using-raml-data-type-system)). - -Please note that "schema" is an alias for the equivalent "type" node, for compatibility with RAML 0.8 and is deprecated. API definitions should use the "type" node, as the "schema" alias may be removed in a future RAML version. The "type" node allows for XML and JSON schemas (see [Using RAML Data Type System](#using-raml-data-type-system)). - -#### Using RAML Data Type System - -RAML's type system allows seamless integration of JSON and XML schemas as type definitions. That follows the same rules as using **schemas** or **schema**. Both are synonymous to **types** and **type**, with the restriction that **type** and **schema** are mutually exclusive. +RAML allows to not only define data using the type system, although it is recommended, but also provides mechanism to define them in XML and/or JSON schemas. RAML's type system allows seamless integration of JSON and XML schemas as type definitions. The following examples show how to include an external JSON schema into a root-level type definition and a body declaration. @@ -1289,6 +1229,10 @@ types: single: boolean ``` +A RAML Processor MUST be able to interpret JSON Schema and XML Schema. + +Please note that the properties "schemas" and "types" are completely synonymous, so are "schema" and "type" for compatibility with RAML 0.8, but "schemas" and "schema" are deprecated. API definitions should use "types" and "type", as "schemas" and "schema" may be removed in a future RAML version. + ### Inheritance and Specialization When declaring a RAML Type you are always inheriting from, or specializing, an existing type. The general syntax for inheritance is: From 961bfb075322f075ab2545bb2634baaf24a5d8b9 Mon Sep 17 00:00:00 2001 From: Christian Vogel Date: Wed, 13 Apr 2016 13:37:04 +0100 Subject: [PATCH 092/241] added some text that JSON and XML schemas are not allowed in type expressions in generally, and also added an example --- versions/raml-10/raml-10.md | 14 +++++++++++++- 1 file changed, 13 insertions(+), 1 deletion(-) diff --git a/versions/raml-10/raml-10.md b/versions/raml-10/raml-10.md index 0fe06dc0..e4e8f3cc 100644 --- a/versions/raml-10/raml-10.md +++ b/versions/raml-10/raml-10.md @@ -1208,7 +1208,7 @@ types: type: !include person.json ``` -A RAML processor MUST not allow types that define an XML or JSON schema to participate in type inheritance or specialization. In other words: You cannot define sub-types of these types that declare new properties, add restrictions, and set or declare facets. You can, however, create simple type wrappers that add annotations, examples or a description. +A RAML processor MUST not allow types that define an XML or JSON schema to participate in type inheritance or specialization, or effectively in any [type expression](#type-expressions). In other words: You cannot define sub-types of these types that declare new properties, add restrictions, and set or declare facets. You can, however, create simple type wrappers that add annotations, examples or a description. The following is a fully valid example. @@ -1229,6 +1229,18 @@ types: single: boolean ``` +Another invalid case is the following example where the type `Person` is being used for a property type. + +```yaml +types: + Person: + type: !include person.json + description: this is a schema describing person + Board: + properties: + members: Person[] # invalid use of type expression '[]' and as a property type + ``` + A RAML Processor MUST be able to interpret JSON Schema and XML Schema. Please note that the properties "schemas" and "types" are completely synonymous, so are "schema" and "type" for compatibility with RAML 0.8, but "schemas" and "schema" are deprecated. API definitions should use "types" and "type", as "schemas" and "schema" may be removed in a future RAML version. From 6574311afa72665373d45bf716664f7c33c42cc8 Mon Sep 17 00:00:00 2001 From: Christian Vogel Date: Wed, 13 Apr 2016 22:00:26 +0100 Subject: [PATCH 093/241] incorporated feedback --- versions/raml-10/raml-10.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/versions/raml-10/raml-10.md b/versions/raml-10/raml-10.md index 02ce68b9..9d2c45c3 100644 --- a/versions/raml-10/raml-10.md +++ b/versions/raml-10/raml-10.md @@ -434,7 +434,7 @@ declarations may have; certain type declarations may have other properties. |:----------|:----------| | default? | Provides a default value for a type. | schema? | Alias for the equivalent "type" property, for compatibility with RAML 0.8. Deprecated - API definitions should use the "type" property, as the "schema" alias for that property name may be removed in a future RAML version. The "type" property allows for XML and JSON schemas. -| type? | A base type which the current type extends, or more generally a type expression. The value of a type node must be the name of either a user-defined type or one of the built-in types (object, array, or a scalar type), or a JSON or XML Schema. +| type? | A base type which the current type extends, or more generally a type expression. The value of a `type` node MUST be either a) the name of a user-defined type or b) the name of a built-in RAML data type (object, array, or scalar type) or c) an inline type declaration. | example? | An example of an instance of this type. This can be used, e.g., by documentation generators to generate sample values for an object of this type. The `example` property MUST not be available when the `examples` property is already defined. | examples? | An object containing named examples of instances of this type. This can be used, e.g., by documentation generators to generate sample values for an object of this type. The `examples` property MUST not be available when the `example` property is already defined. See section [Examples](#defining-examples-in-raml) for more information. | displayName? | An alternate, human-friendly name for the type From 51d5a110ddbc774a827634879ad5869bd8df2921 Mon Sep 17 00:00:00 2001 From: Christian Vogel Date: Thu, 14 Apr 2016 13:10:24 +0100 Subject: [PATCH 094/241] make explicit where XML and JSON schemas are not allowed --- versions/raml-10/raml-10.md | 2 ++ 1 file changed, 2 insertions(+) diff --git a/versions/raml-10/raml-10.md b/versions/raml-10/raml-10.md index e4e8f3cc..efa1cebc 100644 --- a/versions/raml-10/raml-10.md +++ b/versions/raml-10/raml-10.md @@ -1243,6 +1243,8 @@ types: A RAML Processor MUST be able to interpret JSON Schema and XML Schema. +XML schema MUST NOT be used where the media type does not allow XML-formatted data, and JSON schema MUST NOT be used where the media type does not allow JSON-formatted data. XML and JSON schemas are also FORBIDDEN in any declaration of query parameters, query string, and headers. + Please note that the properties "schemas" and "types" are completely synonymous, so are "schema" and "type" for compatibility with RAML 0.8, but "schemas" and "schema" are deprecated. API definitions should use "types" and "type", as "schemas" and "schema" may be removed in a future RAML version. ### Inheritance and Specialization From bea1770f9fa66920932abbbd95fc019e411d59a2 Mon Sep 17 00:00:00 2001 From: Christian Vogel Date: Fri, 15 Apr 2016 12:06:22 +0100 Subject: [PATCH 095/241] some content improvements: wordsmithing, English, etc. --- versions/raml-10/raml-10.md | 181 ++++++++++++++++++------------------ 1 file changed, 88 insertions(+), 93 deletions(-) diff --git a/versions/raml-10/raml-10.md b/versions/raml-10/raml-10.md index 912e6063..21b77db6 100644 --- a/versions/raml-10/raml-10.md +++ b/versions/raml-10/raml-10.md @@ -6,101 +6,108 @@ RAML is a language for the definition of HTTP-based APIs that embody most or all ## Status of this Document -This document reflects the RAML 1.0 specification. The contents of this document were derived from the consensus of its authors and through the feedback of RAML 0.8 users. We strongly recommend that implementers and users of the RAML 0.8 specification update their software and API definitions to this version of the RAML specification. - +This document constitutes the RAML 1.0 specification. The consensus of specification authors and RAML 0.8 users determines the contents of this document. We strongly recommend that implementers and users of the RAML 0.8 specification update their software and API definitions to this version of the RAML specification. ## Terminology and Conformance Language -Normative text is text that describes elements of the specification that are indispensable and/or contain the conformance language keywords as defined by the [IETF RFC 2119](https://www.ietf.org/rfc/rfc2119.txt) "Key words for use in RFCs to Indicate Requirement Levels". Informative text is text that is potentially helpful to the user, but not indispensable to the specification and can be changed, added, or deleted editorially without negative implications to the implementation of the specification. Informative text does not contain any conformance keywords. +Normative text describes one or both of the following kinds of elements: + +* Vital elements of the specification +* Elements that contain the conformance language key words as defined by [IETF RFC 2119](https://www.ietf.org/rfc/rfc2119.txt) "Key words for use in RFCs to Indicate Requirement Levels" + +Informative text is potentially helpful to the user, but dispensable. Informative text can be changed, added, or deleted editorially without negatively affecting the implementation of the specification. Informative text does not contain conformance keywords. All text in this document is, by default, normative. -The keywords "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this document are to be interpreted as described in the [IETF RFC 2119](https://www.ietf.org/rfc/rfc2119.txt) "Keywords for use in RFCs to Indicate Requirement Levels". +The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this document are to be interpreted as described in [IETF RFC 2119](https://www.ietf.org/rfc/rfc2119.txt) "Key words for use in RFCs to Indicate Requirement Levels". ## Definitions and Terminology ### General -For this specification, **API definition** is used to denote the description of an API using this specification and **RAML Specification** refers to the current document. +In this specification, **API definition** means an API using this specification. + +**RAML Specification** refers to this document. -**REST** is used in the context of an API implemented using some or all of the principles of REST. The REST acronym stands for Representational State Transfer and was first introduced and defined in 2000 by Roy Fielding in his doctoral dissertation [REST](http://www.ics.uci.edu/~fielding/pubs/dissertation/rest_arch_style.htm). +**REST** is used in the context of an API implemented using some or all of the principles of REST (Representational State Transfer), which was introduced and first defined in 2000 in Chapter 5, [REST](http://www.ics.uci.edu/~fielding/pubs/dissertation/rest_arch_style.htm), of the doctoral dissertation *"Architectural Styles and the Design of Network-based Software Architecture"* by Roy Fielding. A **resource** is the conceptual mapping to an entity or set of entities. -Optional properties are indicated with trailing question marks (e.g. **description?**). +A trailing question mark, for example **description?**, indicates an optional property. ### Template URI -A template URI refers to any URI parameters using curly brackets ({}) to mark a section inside a resource's relative URI as variable element. +A template URI refers to a URI parameter, which is a variable element, enclosed in curly brackets ({}) inside a relative URI of a resource. -RAML fully supports Level 2 as defined in [RFC6570](https://tools.ietf.org/html/rfc6570) for any template URIs. +RAML fully supports Level 2 as defined in [RFC6570](https://tools.ietf.org/html/rfc6570) for URI Templates. + +### Markdown + +Throughout this specification, **Markdown** means [GitHub-Flavored Markdown](https://help.github.com/articles/github-flavored-markdown/). ## Introduction -This specification describes the RESTful API Modeling Language (RAML). RAML is a human- and machine-readable language for the definition of a RESTful application programming interface (API). RAML is designed to improve the specification of such interfaces by providing a format that can serve as a useful contract between the API provider and the API consumers, for example to facilitate providing user documentation and source code stubs for client and server implementations, thereby streamlining and enhancing the definition and development of interoperable applications that utilize RESTful APIs. +This specification describes the RESTful API Modeling Language (RAML). RAML is a human- and machine-readable language for the definition of a RESTful application programming interface (API). RAML is designed to improve the specification of the API by providing a format that the API provider and API consumers can use as a mutual contract. RAML can, for example, facilitate providing user documentation and source code stubs for client and server implementations. Such provisions streamline and enhance the definition and development of interoperable applications that utilize RESTful APIs. -RAML introduces the innovative concept of resource types and traits for characterizing and reusing patterns of resources and methods on those resources, thereby minimizing the amount of repetition required to specify a RESTful API's design and promoting consistency within and across APIs. +RAML introduces the innovative concept of resource types and traits for characterizing and reusing patterns of resources and associated methods. Using resource types and traits minimizes the repetition in a RESTful API design and promotes consistency within and across APIs. This document is organized as follows: -* **Basic Information**. Explains how to describe core aspects of the API, such as its name, title, location (or URI), and defaults. Describes how to include supporting documentation for the API. -* **Data Types**. Describes a means to model API data via a streamlined type system, which also encompasses JSON and XML Schema. -* **Resources**. Describes how to specify an API's resources and nested resources, as well as URI parameters in any URI templates. -* **Methods**. Describes how to specify the methods on the API’s resources, and their request headers, query parameters, and request bodies. -* **Responses**. Describes the specification of API responses, including status codes, media types, response headers and response bodies. -* **Resource Types and Traits**. Describes the optional mechanism for using RAML resource types and traits to characterize resources so as to avoid unnecessary repetition in an API's definition and promote consistency and reuse. -* **Security**. Describes the mechanisms available in RAML to specify an API’s security schemes. -* **Annotations**. Describes a mechanism for extending a RAML specification by defining strongly-typed annotations and applying them throughout the specification. -* **Includes, Libraries, Overlays, and Extensions**. Describes how an API’s definition may be composed of externalized definition documents, how collections of such definitions can be packaged as libraries, how layers of metadata may be separated from and overlaid on top of a RAML document, and how an API specification can be extended with additional functionality. +* **Basic Information**. How to describe core aspects of the API, such as its name, title, location (or URI), and defaults and how to include supporting documentation for the API. +* **Data Types**. Modeling API data through a streamlined type system that encompasses JSON and XML Schema. +* **Resources**. How to specify API resources and nested resources, as well as URI parameters in any URI templates. +* **Methods**. How to specify the methods on API resources and their request headers, query parameters, and request bodies. +* **Responses**. The specification of API responses, including status codes, media types, response headers, and response bodies. +* **Resource Types and Traits**. The optional use of RAML resource types and traits to characterize resources. +* **Security**. Specifying an API security scheme in RAML. +* **Annotations**. Extending a RAML specification by defining strongly-typed annotations and applying them throughout the specification. +* **Includes, Libraries, Overlays, and Extensions**. How an API definition can consist of externalized definition documents, packaging collections of such definitions into libraries, separating and overlaying layers of metadata on a RAML document, and extending an API specification with additional functionality. ## What's New and Different in RAML 1.0 * **Data types**: a unified, streamlined, and powerful way to model data wherever it appears in an API. - * Uniformly covers bodies, URI parameters, headers, and query parameters (and no more need for a separate formParameters construct) - * Can wrap XML Schema and JSON Schema and even refer to sub-schemas within them, but in many cases just obviates them - * Much easier than JSON Schema or XML Schema, and all in YAML -* **Examples**: multiple examples, expressible in YAML, and annotatable (so semantics can be injected) + * Uniformly covers bodies, URI parameters, headers, and query parameters and eliminates the need for a separate formParameters construct + * Supports wrapping XML Schema and JSON Schema and even referring to sub-schemas, but in many cases just obviates the schemas + * Simplifies coding, compared to the JSON Schema or XML Schema, by virtue of being YAML-based +* **Examples**: multiple examples, expressible in YAML, and annotatable, so semantics can be injected * **Annotations**: a tried-and-tested, strongly-typed mechanism for extensibility -* **Libraries**: more capable modularization for broad reuse of API artifacts -* **Overlays** and **Extensions**: further extensibility via separated files +* **Libraries**: improved modularity for broad reuse of API artifacts +* **Overlays** and **Extensions**: increased extensibility through separated files * **Improved Security Schemes**: - * More complete OAuth support - * Support pass-through (key-based) security schemes - * Extension points -* **Several smaller changes** for consistency and expressivity, for example: - * Array-valued properties can be expressed as scalars when the array has only one member - * Ambiguities have been clarified, e.g. the optionality of baseUri and the overloading rules + * Wider OAuth support + * Support for pass-through (key-based) security schemes +* **Several smaller changes** for consistency and expressivity ## Markup Language -This specification uses [YAML 1.2](http://www.yaml.org/spec/1.2/spec.html) as its underlying format. YAML is a human-readable data format that aligns well with the design goals of this specification. As in YAML, all nodes (keys, values, tags, etc) are case-sensitive. +This specification uses [YAML 1.2](http://www.yaml.org/spec/1.2/spec.html) as its underlying format. YAML is a human-readable data format that aligns well with the design goals of this specification. As in YAML, all nodes such as keys, values, and tags, are case-sensitive. -RAML API definitions are YAML 1.2-compliant documents that begin with a REQUIRED YAML-comment line that indicates the RAML version, as follows. +RAML API definitions are YAML 1.2-compliant documents that begin with a REQUIRED YAML-comment line that indicates the RAML version, as follows: ```yaml #%RAML 1.0 title: My API ``` -The first line of a RAML specification compliant document MUST match the [IETF RFC5234](https://tools.ietf.org/html/rfc5234) – Augmented BNF for Syntax Specifications: +The first line of a RAML specification-compliant document MUST match the [IETF RFC5234](https://tools.ietf.org/html/rfc5234) – Augmented BNF for Syntax Specifications: “#%RAML” SP “1.0” SP [FragmentType] CRLF -With the _FragmentType_ being NOT ALLOWED in API definitions, and is OPTIONAL for the specification of RAML fragment documents. RAML fragment documents are reusable RAML modules that are referenced or included into a larger API definition. Please refer to the [Modularization](#modularization) section for more information about RAML fragments. +The _FragmentType_ is NOT ALLOWED in API definitions and is OPTIONAL for the specification of [RAML fragment](#typed-fragments) documents. RAML fragment documents are reusable RAML modules that a larger API definition references or includes. -The media type _application/raml+yaml_ and its associated file extension _.raml_ SHALL be used to designate files containing RAML API definitions, RAML fragments and files that contain RAML markup. RAML is also capable of including documents with other media types, e.g., “application/schema+json”, “application/yaml”. +The media type _application/raml+yaml_ and its associated file extension _.raml_ SHALL be used to designate files containing RAML API definitions, RAML fragments, and files that contain RAML markup. RAML is also capable of including documents of other media types, such as “application/schema+json” and “application/yaml”. -In order to facilitate the automated processing of RAML documents, RAML imposes some restrictions and requirements in addition to the core YAML 1.2 specification. The following list enumerates some of these requirements and restrictions: +To facilitate the automated processing of RAML documents, RAML imposes the following restrictions and requirements in addition to the core YAML 1.2 specification: -1. The first line of a RAML file consists of a YAML comment that specifies the RAML version. Therefore RAML processors cannot completely ignore all YAML comments. -2. The order of some properties at given levels within a RAML document has significance. Therefore processors are expected to preserve this ordering. -3. Property names, also known as Keys, at given levels are not repeatable. Although YAML allows such repetition duplicate-keys will overwriting previously specified values. +* The first line of a RAML file consists of a YAML comment that specifies the RAML version. Therefore, RAML processors cannot completely ignore all YAML comments. +* The order of some properties at certain levels within a RAML document is significant. Therefore, processors are expected to preserve this ordering. +* Property names, also known as Keys, at certain levels are not repeatable. Although YAML allows such repetition, the value of a duplicate key, key 2 for example, overwrites the value of the duplicated key 1. ## The Root of the Document -The root section of the RAML document describes the basic information of an API, such as its title and version, as well as defining assets used elsewhere in the RAML document such as types and traits. +The root section of the RAML document describes the basic information about an API, such as its title and version. The root section also defines assets used elsewhere in the RAML document, such as types and traits. -RAML-documented API definition properties MAY appear in any order. Processors MUST preserve the order of properties of the same kind within the same node of the definition tree, for example resources that appear at the same level of the resource tree, methods for a given resource, parameters for a given method, properties at the same level in a given type, etc. Processors MUST also preserve the order of items within arrays. +RAML-documented API definition properties MAY appear in any order. Processors MUST preserve the order of properties of the same kind within the same node of the definition tree. Examples of such properties are resources that appear at the same level of the resource tree, methods for a given resource, parameters for a given method, and properties at the same level in a given type. Processors MUST also preserve the order of items within arrays. This example shows a small part of a RAML API definition for the GitHub v3 public API. @@ -129,50 +136,37 @@ The following table enumerates the possible properties at the root of a RAML doc | Property | Description | |:----------|:----------| -| description? | A longer, human-friendly description of the API -| (<annotationName>)? | Annotations to be applied to this API. Annotations are any property whose key begins with "(" and ends with ")" and whose name (the part between the beginning and ending parentheses) is a declared annotation name. See section [Annotations](#annotations) for more information. -| schemas? | Alias for the equivalent "types" property, for compatibility with RAML 0.8. Deprecated - API definitions should use the "types" property, as the "schemas" alias for that property name may be removed in a future RAML version. The "types" property allows for XML and JSON schemas. -| types? | Declarations of (data) types for use within this API. The value is a map where each key represents the name of the type and the value a type declaration. See section [RAML Data Types](#raml-data-types) for more information. -| traits? | Declarations of traits for use within this API. See section [Resource Types and Traits](#resource-types-and-traits) for more information. -| resourceTypes? | Declarations of resource types for use within this API. See section [Resource Types and Traits](#resource-types-and-traits) for more information. -| annotationTypes? | Declarations of annotation types for use by annotations. See section [Annotation Types](#declaring-annotation-types) for more information. -| securitySchemes? | Declarations of security schemes for use within this API. See section [Security Schemes](#security-schemes) for more information. -| uses? | Importing external libraries that can be used within the API. See section [Libraries](#libraries) for more information. -| title | Short plain-text label for the API -| version? | The version of the API, e.g. "v1" -| baseUri? | A URI that's to be used as the base of all the resources' URIs. Often used as the base of the URL of each resource, containing the location of the API. Can be a [template URI](#template-uri). See section [Base URI and Base URI Parameters](#base-uri-and-base-uri-parameters) for more information. -| baseUriParameters? | Named parameters used in the baseUri (template). See section [Base URI and Base URI Parameters](#base-uri-and-base-uri-parameters) for more information. -| protocols? | The protocols supported by the API. The protocols property MUST contain one or more of the supported protocols: "HTTP", "HTTPS". (case-insensitive). -| mediaType? | Default media types to use for request and response bodies (payloads), e.g. "application/json" -| securedBy? | The security schemes that apply to every resource and method in the API. See section [Applying Security Schemes](#applying-security-schemes) for more information. -| /<relativeUri>? | The resources of the API, identified as relative URIs that begin with a slash (/). Every property whose key begins with a slash (/), and is either at the root of the API definition or is the child property of a resource property, is a resource property, e.g.: /users, /{groupId}, etc. -| documentation? | Additional overall documentation for the API. See section [User Documentation](#user-documentation) for more information. - -### API Title -The **title** property is a short plain text label for the API. It MUST be specified, and its value is a string. Its value SHOULD be suitable for use as a title for the contained user documentation. - -### API Version - -The OPTIONAL **version** property specifies a version of the API (as a whole). Its value is a string. API owners SHOULD consider carefully their versioning approach and communicate the current version through the version property. - -### API Description - -The OPTIONAL **description** property describes the overall API in a human friendly, extended manner. The value of the description property is a markdown string. More structured documentation SHOULD be included throughout the structure of the API definition and in the documentation property. +| title | A short, plain-text label for the API. Its value is a string. +| description? | A substantial, human-friendly description of the API. Its value is a string and MAY be formatted using [markdown](#markdown). +| version? | The version of the API, for example "v1". Its value is a string. +| baseUri? | A URI that serves as the [base for URIs](#base-uri-and-base-uri-parameters) of all resources. Often used as the base of the URL of each resource containing the location of the API. Can be a [template URI](#template-uri). +| baseUriParameters? | Named parameters used in the [baseUri](#base-uri-and-base-uri-parameters) (template). +| protocols? | The [protocols](#protocols) supported by the API. +| mediaType? | The [default media types](#default-media-type) to use for request and response bodies (payloads), for example "application/json". +| documentation? | Additional overall [documentation](#user-documentation) for the API. +| schemas? | An alias for the equivalent "types" property for compatibility with RAML 0.8. Deprecated - API definitions should use the "types" property because a future RAML version might remove the "schemas" alias for that property name. The "types" property supports XML and JSON schemas. +| types? | Declarations of [(data) types](#raml-data-types) for use within the API. +| traits? | Declarations of [traits](#resource-types-and-traits) for use within the API. +| resourceTypes? | Declarations of [resource types](#resource-types-and-traits) for use within the API. +| annotationTypes? | Declarations of [annotation types](#declaring-annotation-types) for use by annotations. +| (<annotationName>)? | [Annotations](#annotations) to be applied to this API. An annotation is a property having a key that begins with "(" and ends with ")". The text enclosed in parentheses is the annotation name. +| securitySchemes? | Declarations of [security schemes](#security-schemes) for use within the API. +| securedBy? | The [security schemes](#applying-security-schemes) that apply to every resource and method in the API. +| uses? | Imported external [libraries](#libraries) for use within the API. +| /<relativeUri>? | The resources of the API, identified as relative URIs that begin with a slash (/). A [resource property](#resources-and-nested-resources) is one that begins with the slash and is either at the root of the API definition or a child of a resource property. For example, /users and /{groupId}. ### User Documentation The OPTIONAL **documentation** property includes a variety of documents that serve as user guides and reference documentation for the API. Such documents can clarify how the API works or provide technical and business context. -The value of the documentation property is an array of one or more documents. Each document is an object that MUST contain exactly two properties, **title** and **content**, with non-empty string values. The content property's value is a markdown string. - -The structure of documentation object is described by following table. +The value of the documentation property is a sequence of one or more documents. Each document is an object that MUST have exactly two properties described in following table: | Property | Description | |:----------|:----------| -| title | Title of documentation section -| content | Content of documentation section +| title | Title of the document. Its value MUST be a non-empty string. +| content | Content of the document. Its value MUST be a non-empty string and MAY be formatted using [markdown](#markdown). -This example shows an API definition with two user documents. +This example shows an API definition having two user documents. ```yaml #%RAML 1.0 @@ -201,7 +195,7 @@ If the baseUri value is a [Template URI](#template-uri), the following reserved |:----------|:----------| | version | The value of the root-level version property -Any other URI template variables appearing in the baseUri MAY be described explicitly within a **baseUriParameters** property at the root of the API definition. The baseUriParameters property has the same structure and semantics as the uriParameters property on a resource property, except that it specifies parameters in the base URI rather than a resource's relative URI. See the section [Template URIs and URI parameters](#template-uris-and-uri-parameters) for information about the uriParameters property. +Any other URI template variables appearing in the baseUri MAY be described explicitly within a **baseUriParameters** property at the root of the API definition. The baseUriParameters property has the same structure and semantics as the [uriParameters](#template-uris-and-uri-parameters) property on a resource property, except that it specifies parameters in the base URI rather than the relative URI of a resource. The following example RAML API definition uses a [Template URI](#template-uri) as the base URI. @@ -224,9 +218,7 @@ baseUriParameters: description: The name of the bucket ``` -When the base URI ends in one or more slashes (`/`), those trailing slashes are to be omitted in constructing the absolute paths for the resources using that base URI. - -For example, in +When the base URI ends in one or more slashes (`/`), those trailing slashes are omitted in the absolute paths for the resources using that base URI. For example, in the following snippet, the absolute paths for the resources are `http://api.test.com/common/users` and `http://api.test.com/common/users/groups`. ```yaml baseUri: http://api.test.com/common/ @@ -234,9 +226,7 @@ baseUri: http://api.test.com/common/ /groups: ``` -the absolute paths for the two resources are `http://api.test.com/common/users` and `http://api.test.com/common/users/groups`. - -In a more complicated examples with consecutive slashes in multiple places, note that only trailing slashes in the base URI are collapsed: +In the following, more complicated example with consecutive slashes in multiple places, only trailing slashes in the base URI are collapsed, leading to these absolute paths to resources: `//api.test.com//common/`, `//api.test.com//common//users/`, and `//api.test.com//common//users//groups//`. ```yaml baseUri: //api.test.com//common// @@ -244,11 +234,10 @@ baseUri: //api.test.com//common// /users/: /groups//: ``` -leads to the following 3 resource absolute paths: `//api.test.com//common/`, `//api.test.com//common//users/` and `//api.test.com//common//users//groups//`. ### Protocols -The OPTIONAL **protocols** property specifies the protocols that an API supports. If the protocols property is not explicitly included, the protocol(s) specified at the baseUri property is (are) used; if the protocols property is specified explicitly, it overrides any protocol specified in the baseUri property. The protocols property MUST be a non-empty array of strings, of values HTTP and/or HTTPS, and is case-insensitive. +The OPTIONAL **protocols** property specifies the protocols that an API supports. If the protocols property is not explicitly specified, one or more protocols included in the baseUri property is used; if the protocols property is explicitly specified, the property specification overrides any protocol included in the baseUri property. The protocols property MUST be a non-empty array of strings, of values HTTP and/or HTTPS, and is case-insensitive. The following is an example of an API endpoint that accepts both HTTP and HTTPS requests. @@ -426,9 +415,15 @@ RAML Types in a nutshell: ### Type Declarations Types may be declared inline, wherever the API expects data, or in an OPTIONAL **types** property at the root of the API -or in an included library. Types declarations are used to extend built-in types or other custom types, as well as to -add more information to types such as specific examples or annotations. Here are the properties that all type -declarations may have; certain type declarations may have other properties. +or in an included library. The value is a map where each key represents the name of the type and its value is a type declaration. + +```yaml +types: + Person: # key name + # value is a type declaration +``` + +Types declarations are used to extend built-in types or other custom types, as well as to add more information to types such as specific examples or annotations. Here are the properties that all type declarations may have; certain type declarations may have other properties. | Property | Description | |:----------|:----------| @@ -1832,7 +1827,7 @@ The OPTIONAL **displayName** property provides a friendly name for the method an ### Method-level Description -The OPTIONAL **description** property describes the operation of the method on the resource. Its value is a markdown string. It is RECOMMENDED that all methods provide such a description. +The OPTIONAL **description** property describes the operation of the method on the resource. Its value is a string and MAY be formatted using [markdown](#markdown). It is RECOMMENDED that all methods provide such a description. The following example shows a resource, /jobs, with post and get methods declared. @@ -2848,7 +2843,7 @@ Annotation types are declared using the OPTIONAL root-level **annotationTypes** |Property |Description | |:--------|:------------| | displayName? | The displayName attribute specifies the $self's display name. It is a friendly name used only for display or documentation purposes. If displayName is not specified, it defaults to the element's key (the name of the property itself). -| description? | The description attribute describes the intended use or meaning of an annotation. This value MAY be formatted using markdown. +| description? | The description attribute describes the intended use or meaning of an annotation. Its value is a string and MAY be formatted using [markdown](#markdown). | (<annotationName>)? | Annotations to be applied to this annotation type. Annotations are any property whose key begins with “(“ and ends with “)” and whose name (the part between the beginning and ending parentheses) is a declared annotation name. See section [Annotations](#annotations) for more information. | allowedTargets? | Restrictions on where annotations of this type can be applied. If this property is specified, annotations of this type may only be applied on a property corresponding to one of the target names specified as the value of this property. Value MUST be one or more of the options described in table [Annotation Target Location](#annotation-target-location). @@ -3223,7 +3218,7 @@ A library is an object whose allowed properties are enumerated in the following |Property | Description | |:--------|:------------| | types?
    schemas?
    resourceTypes?
    traits?
    securitySchemes?
    annotationTypes?
    (<annotationName>)?
    uses? | The definition of each property is the same as that of the corresponding property in the root of a RAML document. Annotation properties are allowed as in any other RAML document. -| usage | Describes the content or purpose of a specific library. The content may be described in markdown. +| usage | Describes the content or purpose of a specific library. Its value is a string and MAY be formatted using [markdown](#markdown). The following example shows a simple library as a standalone, reusable RAML fragment document. From 55313398fe3fa3569e0c91aa899b472da7a6865b Mon Sep 17 00:00:00 2001 From: krishahn Date: Sat, 16 Apr 2016 09:14:53 -0700 Subject: [PATCH 096/241] copyedit default media types section + a few minor edits --- versions/raml-10/raml-10.md | 16 ++++++++-------- 1 file changed, 8 insertions(+), 8 deletions(-) diff --git a/versions/raml-10/raml-10.md b/versions/raml-10/raml-10.md index 21b77db6..f1de2c47 100644 --- a/versions/raml-10/raml-10.md +++ b/versions/raml-10/raml-10.md @@ -190,7 +190,7 @@ documentation: The OPTIONAL **baseUri** property specifies a URI as an identifier for the API as a whole, and MAY be used the specify the URL at which the API is served (its service endpoint), and which forms the base of the URLs of each of its resources. The baseUri property's value is a string that MUST conform to the URI specification [RFC2396](https://www.ietf.org/rfc/rfc2396.txt) or a [Template URI](#template-uri). If the baseUri value is a [Template URI](#template-uri), the following reserved base URI parameter is available. - +r | URI Parameter | Value | |:----------|:----------| | version | The value of the root-level version property @@ -251,11 +251,11 @@ baseUri: https://na1.salesforce.com/services/data/{version}/chatter ### Default Media Types -The media types expected from API requests that contain a body, and returned by API responses, can be defaulted by specifying the OPTIONAL **mediaType** property, so they do not need to be specified within every body definition. +Specifying the OPTIONAL **mediaType** property sets the default for return by API requests having a body and for the expected responses. You do not need to specify the media type within every body definition. -The value of the mediaType property MUST be a sequence of media type strings or a single string if there is only one default media; with the premise that all of them are described by exactly the same types and/or examples. Each value need to conform to the media type specification in [RFC6838](https://tools.ietf.org/html/rfc6838). +The value of the mediaType property MUST be a sequence of type name strings or a single type name string. The mediatype applies to requests having a body, the expected responses, and examples using the same sequence of type name strings. Each value needs to conform to the media type specification in [RFC6838](https://tools.ietf.org/html/rfc6838). -This example shows a RAML snippet for an API that accepts and returns a JSON-formatted body. If the remainder of this API's specification doesn't explicitly specify another media type, this API only accepts and returns JSON-formatted bodies. +This example shows a RAML snippet for an API that accepts and returns a JSON-formatted body. If the remainder of this API specification does not explicitly specify another media type, this API accepts and returns only JSON-formatted bodies. ```yaml #%RAML 1.0 @@ -263,7 +263,7 @@ title: New API mediaType: application/json ``` -Or the alternative syntax if there is more than one default media type. +This example shows a RAML snippet for an API that accepts and returns JSON- or XML-formatted bodies. ```yaml #%RAML 1.0 @@ -271,7 +271,7 @@ title: New API mediaType: [ application/json, application/xml ] ``` -Default media types can be overridden by defining a `mediaType` node explicitly to a [body](#bodies) of an API request or response. When one defines a root-level `mediaType` node and then override that in a body by defining explicitly another or the same media type node, none of the root level media types apply to that node, other than the media types explicitly defined within that node. The example below shows a RAML snippet that illustrates that behavior. The resource `/list` returns a `Person[]` body represented as either JSON or XML. On the other hand, the resource `/send` overrides the default media types with an explicit definition of an `application/json` node and therefore only accepts a JSON-formatted body. +Explicitly defining a `mediaType` node for a [body](#bodies) of an API request or response overrides the default media type, as shown in the following example. The resource `/list` returns a `Person[]` body represented as either JSON or XML. The resource `/send` overrides the default media type by explicitly defining an `application/json` node. Therefore, the resource `/send` returns only a JSON-formatted body. ```yaml #%RAML 1.0 @@ -562,7 +562,7 @@ When an Object Type does not contain the "properties" property, the object is as #### Additional Properties -By default any instance of an object can have additional properties beyond those specified in its data type `properties` node. Lets assume the following is an instance of the data type `Person` that is described in the previous section. +By default any instance of an object can have additional properties beyond those specified in its data type `properties` node. Let's assume the following is an instance of the data type `Person` that is described in the previous section. ```yaml Person: @@ -592,7 +592,7 @@ types: type: string ``` -This restricts any additional properties whose keys start with "note" followed by one or more digits to be a string. Where as the example of an object instance with an additional `note` property with value "US" is valid, the following is not: +This restricts any additional properties whose keys start with "note" followed by one or more digits to be a string. Where as the example of an object instance with an additional `note` property with value "US" is valid, the following is not: ```yaml Person: From 3cbc1074f8b541845aeba44995e87e9f7f054e8b Mon Sep 17 00:00:00 2001 From: krishahn Date: Sat, 16 Apr 2016 12:11:59 -0700 Subject: [PATCH 097/241] remove errant r --- versions/raml-10/raml-10.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/versions/raml-10/raml-10.md b/versions/raml-10/raml-10.md index f1de2c47..d35525d3 100644 --- a/versions/raml-10/raml-10.md +++ b/versions/raml-10/raml-10.md @@ -190,7 +190,7 @@ documentation: The OPTIONAL **baseUri** property specifies a URI as an identifier for the API as a whole, and MAY be used the specify the URL at which the API is served (its service endpoint), and which forms the base of the URLs of each of its resources. The baseUri property's value is a string that MUST conform to the URI specification [RFC2396](https://www.ietf.org/rfc/rfc2396.txt) or a [Template URI](#template-uri). If the baseUri value is a [Template URI](#template-uri), the following reserved base URI parameter is available. -r + | URI Parameter | Value | |:----------|:----------| | version | The value of the root-level version property From 80fbd469c5ced4ebced77f39eb2144f0131d89d9 Mon Sep 17 00:00:00 2001 From: krishahn Date: Sat, 16 Apr 2016 16:04:59 -0700 Subject: [PATCH 098/241] copyedits --- versions/raml-10/raml-10.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/versions/raml-10/raml-10.md b/versions/raml-10/raml-10.md index 21b77db6..170d47b7 100644 --- a/versions/raml-10/raml-10.md +++ b/versions/raml-10/raml-10.md @@ -294,7 +294,7 @@ types: ### Default Security -The security schemes to be applied to every method of every resource in the API can be defaulted by specifying the OPTIONAL **securedBy** property. Its value is an array of security scheme names. If this property is specified, every method of every resource is protected by the specified security schemes. See section [Applying Security Schemes](#applying-security-schemes) for more information, including how to resolve application of multiple security schemes via inheritance. +Specifying the OPTIONAL **securedBy** property sets the default security schemes for, and protects, every method of every resource in the API. The value of the property is an array of security scheme names. See section [Applying Security Schemes](#applying-security-schemes) for more information, including how to resolve the application of multiple security schemes through inheritance. The following example shows an API allowing access through either an OAuth 2.0 security scheme or an OAuth 1.1 security scheme. From 05a4b4faea877b4db4f53f80748c58f6ccd1cff3 Mon Sep 17 00:00:00 2001 From: krishahn Date: Sat, 16 Apr 2016 22:07:10 -0700 Subject: [PATCH 099/241] copyediting --- versions/raml-10/raml-10.md | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/versions/raml-10/raml-10.md b/versions/raml-10/raml-10.md index 21b77db6..6089dcd6 100644 --- a/versions/raml-10/raml-10.md +++ b/versions/raml-10/raml-10.md @@ -313,9 +313,9 @@ securitySchemes: ### Introduction -RAML 1.0 introduces the notion of **data types**, which provide a concise and powerful way of describing the data in your API, and add rules for validating instances of data against the type declaration, so an instance is valid when it adheres to all rules for the type. The data can be in a URI parameter (base or resource URI), a query parameter, a request or response header, or of course a request or response body. Some types are built in, while custom types may be defined by extending (inheriting from) the built-in types. In any place where the API expects data, a built-in type may be used to describe the data, or a type may be extended inline to describe that data. Custom types may also be named and then used like any built-in type. +RAML 1.0 introduces the notion of **data types**, which provide a concise and powerful way of describing the data in an API. Data types add rules for validating data against a type declaration. Valid data adheres to all rules for the type. Data types can describe a base or resource URI parameter, a query parameter, a request or response header, or a request or response body. Data types are built-in or custom. A built-in type can be used anywhere the API expects data. Custom types can be defined by extending the built-in types. A type can be extended inline. Custom types can be named and then used like a built-in type. -The RAML example below defines a User type with three properties: firstname and lastname of (built-in) type string, and age of (built-in) type number. This User type is later used to describe the type (schema) for a payload. +The following RAML example defines a User type that includes type declarations for the firstname, lastname, and age properties. The example declares the properties to be of built-in types string and number. Later, the User type serves to describe the type (schema) for a payload. ```yaml #%RAML 1.0 @@ -336,7 +336,7 @@ types: type: User ``` -A RAML type declaration looks somewhat like a JSON schema definition. In fact, RAML types can be used instead of JSON and XML schemas, or coexist with them. The RAML type syntax, however, is designed to be considerably easier and more succinct than JSON and XML schemas while retaining their flexibility and expressiveness. Below is a larger example. +A RAML type declaration resembles a JSON schema definition. In fact, RAML types can be used instead of JSON and XML schemas, or coexist with them. The RAML type syntax, however, is designed to be considerably easier and more succinct than JSON and XML schemas while retaining their flexibility and expressiveness. The following snippet shows a number of examples of type declarations: ```yaml #%RAML 1.0 @@ -381,7 +381,7 @@ types: type: Org ``` -The example above contains a few advanced features. +These examples of type declarations contain the following advanced features: - Optional properties - [Scalar Type Specialization](#scalar-type-specialization) From 028c54591b9654a243cfa58349f3442f81b4bf08 Mon Sep 17 00:00:00 2001 From: krishahn Date: Sat, 16 Apr 2016 22:18:17 -0700 Subject: [PATCH 100/241] copyedits, diagram leadin sentence, crop diagram --- versions/raml-10/images/typesHierarchy.png | Bin 27968 -> 31303 bytes versions/raml-10/raml-10.md | 26 +++++++++++---------- 2 files changed, 14 insertions(+), 12 deletions(-) diff --git a/versions/raml-10/images/typesHierarchy.png b/versions/raml-10/images/typesHierarchy.png index fe95f5f0855d03ff736fbd68e63d8403d178b41a..c702b380de32ff2b6dd1fc8dc8f88055f8c5add7 100644 GIT binary patch literal 31303 zcmce;byQVf)HZq$6$K>(M34~amX=nKICOVNNlABOAWCx(kdp514nexROS%r-^{vhC zeebw`eD~jb9F8-9v-h5BuDRx%>v^7ae#py;KSn1)hrwWv;S%o@VKCHf7!0NS!F})> z^e_`l@OIxoO8gz{2Ktv+mk|zr^Uy{@!yX31z=i&!z+&Q_fnTCIz-2_y=I`R%!$y5l zmJWXP0tSEgR@r58YsOt$`KbP8?}VpUoJZb zKJwsqImN#JVWpot`bQx7nrGxi5H z%xCJ!_*nlV(jW7{oe#EQ^D9Jf#dn+K{-z_5qc-+_n3S9HlEscScVIB=Nt8y^cctbz zNfdf1Tf_?-q@Hy!1MJX!u1{3DHef#Qk`}W2Z?f?BFcp~&l z=$qw=w1=V5=N_v0?f&dT1>h%zW2dxp?lMJ4NqWf zUni7Wh9k-?2YvJl)- zJ1W2EXbBGe=zb)6?5&I9e0TC{E61}Y;#kH1<%LiIZZzTfd86**XIzR5f^j(_bRGM9 zdjqK3q$)d^pRx^#h475yuT?kyMbRIaR%ic`Hh(g!Er&(CvP%pGH0!gm2lLTFL^YcjM@5R6V<)!)v=7|iMymlB$HxYsC$H-e4+-fn3;r;$xM5V z)m7aROL^7~E*7or5!=0K99khEZzeqs@j9|Py$m_hi~%r0;BTM7wehN&%gd`W%Vyr1 z9TQ-YIA%t+R)Wb^z4!GrmgdEoV37BLK#$g5*0%;O6|*clf4%BAh@bY$#jRLmsg09w zC8f_bO9a0wbvH#opT@^qvbg+C&cXYim*t66JUvFLO!U&y(rGsjD@J#$wFy|@8%K8~Y3e7Ux)2r5no(M3n==%qb99M;u z>ttDUyq-;7w6#>ZWPFJ9{=!xc{{OKLkD)A!B%g3%JSqUjv>mCa+`tEdO{O{H=CSBNoRKP!EY`|3p;D+S2ssijl_6G&#qo(h|51V)199<>co;a$4?(gkd z7(dkZmGhxmg7}Ww%=~$^1FM#+t1A)v8I!=SjW}G4^W2pI7ys&`oT$*0(x1SBlSb!m=-1AMn3(R zuu2(SGFEl&{d|VC{2ETTK`o94V3xpQnWtCHol7I@OBhPnv0ikD=7zhu^}ll5#!XA) zbu@bgJ_K@AV)4%pz3xXuoGKu2h%jKV`KN`l|F;wdJqmi!qx-JG=DBzrUTFBIk=W&H zt6KHqFJB{4^t?J0dVGXvL2#Z-2H$=*gjIRa+QW5vOum{62BWq9FE3*t9jDih1gYq1 zABFTqDZemFNWGvOVQyw!HH5d#e00Co8hlyJ3Eg1cX^nZ&%C26reo_1VHMc6FAeAFx zJJ|6-&tvG%Z`RKwJDEgwuScjo{3JW+ns-(tB!6-UE3(IsLVt&eQ^U87rdj(GCy(VL1{NN`?gJ)Iv90ncv z--Pf|O)*=c{~pu0?b}|d6i;b*U1j+|Hj+cPRr@e`;o6N(*u5Z@f2U`qf~$ z&!4GkGuB4~dL!`u$#qmp&FL|++}5hhciaq=QB-C{shIRr@mtB+9nXaII3DS-p`8!b z%XX1?Pe~r+QIaSv=$sURk$Y+gU*7v~oQZ4^<)PZHuO{vuD=-XD0vt8%OAIxPg zQ}*{ocf|e&x~_eBxBZv9wQGSE z!>+)Sf47rmjNWN!^oZ|9EZBERHD}9r$x0=+=b*gmvE_i2@4*1e#!6Rb#0i%vm7&#@ zDvw@%Fg93iFqm$WqJ&iuaX@-JyLUslmmWEfGsf0aM@q|5vyi(H^}9O8ey8dOPLC3$ zzzT%JQW1j}4Mpv*hhNvuHUotZf>WWxS(rt1zN4DtJE)i+r1{Ls1vZ# zC1sz!v`E7@J~+Q$W$GS78C3kRb*{Z~b6e7bs*FMOdjg%|qzI=VH8cu&*Q7xe^o|Ho z7W~;OvW5HG)6%{K!d{$c@52M?M-jr81#DuP*td>K{45-ugO6YckmdU1S^K=Kri0jl zsX(BIcx5K3p_IMh7>`Fb;>BNRw2eDUoxtPCK|Pxxjzg9Ml7n;y?v>Prr?nkHy55}j zuUY8+%CY-->Ir&5M$EU9024U3H1Aw!bI);&bnpBr7C;!|<=c;)*p*;=%e20_fPZy? zK01pOw0|ZSaUg6rU>7fJXFMR$+V9ylxk`;Sp{rxW_|PPa{8c;ZY&g~5w)Ub#a&l;e z`;3_xVoLO)cTlxId%Dxx<>YGqzT&~F29_?TDcY=Hzq$q_TRQtsynkA*^T+ofdyGAd zr;{92C6J%bE_9X%onLKc?i#!+=D*1Q$O0#@EH`Aq@=T!eJtc-~Q3X-m4%sFn5f{vG zE(kYPyAWX68pG5(HrX&eDUDuUJdN)XF) zXGHlm%grx>yJN}8DlWFvQmxb0)(YZ^sj2tU9^Ebhc{Bd9P;CuV_hOm%1&e8(GS;D*f)=FUGv8EARV$b^C8!#Ivkyr?C4YqdSXXbc=vYsgRo&e#kf?Z{~TY@^c`k_D0`vIc2ZI>h9AYQIv?_462-_FAn%o@cK?TA(&W@;YBXDx!~j(*JFx zGRuie|1c(yul>L1p!F47dG-6{s_&9m`vFD=&NzcEC*cq+;}t^(v8+OM-%T*7yA_^kWF;1_j7lm;Me$X@jO?Y`bXZabxsFfV({<(pC zNaaK3cwMe-0vY?C0oQEEaxG?3#|(I9izgfNE2_y-mRpb6px_~LDjTiLr|sYH6T%=^N?(fpL0qM)fP2PZ3>`xSh{D4 zqmStqnMJxdfyw;*-%$4j#qFK>bqiD9vaKZR+1nZL!>1i{P07K+rg*zozR&6Rw#(#& zXzM-v>1%8uT``nD7PnF0QZ0Y*(59Feql2o0_8Gn~yNW+AeQixFWA?8ae}z^cd3m!<^)O(fxlVaGI?QUy={0BUQ{aoYk_qgL(lE~k}-3jbnt5%<$8EnJJ zueooXXLS$UDvH&sTTmHt z!n%%0Mc*I9c)FwpDk!wwwhO<>hdu7B=7wq)^Q`#}N?Wl^egNCtIuTB|y=A$(KP@`^ zyYr*HA1hb<1V&)iv?Uk_oqGa){{?aN_=)clKb!?0Gm7-By-U0-eXeL2#o`^z2YbE3 zm$zL~-2upJ}5=zBjC^w84D75fGS#aBK5jy@ab9^=p$j-Ws$zoAMFC7#SI$_dxlgza<8(~Bm~ibHt>P5I62SweW$LL81)!buFuBPW))k{Rl6#2 zv3_#?O}Je>KS5!n%?^`!uLrkJd?sRf4v!41+Ia&f_sZnS{O==pEW#}Wh$&k14p;a0 z6>-uu-`BBddA_ENZ;7ni=o7Hp+d4^3(ad5S3x30F(?|zM8MRs2?Qm4tR=)WkB!vBUq>< zrb`)s@tU^g1Dm;?dit2O;mv0|^t~Ul!G_QZnvXQ^cs5zD09uXUUvkM5rqp;iAj*^; zZk>`yv#AmlPCLqlJCOB!wi}cdi;qAEd;AQ<2m>x*CRc9lA2y<)dDXF!pdf+SlJ#N8 zIoLKiz-~~|cciHx`b1>fQ5>`!hKQ%_>h(W8pTl68%8|l$;_t|Lu*VmwuPi?GT+_iH z>5DCYJ8oCeh(*k1|vvbM?KR;>a$4aB+)4V3~PK}kuyOmPkZ&VchQ=?a| z=%D%FHld>=U;x+fu&v~Y+x3gzBht4|?g%xi^cP#1H=H1AjcI=J2C^1EKPHgefx)JwxZYkT^R=m4<|D>Y%t8!r`oQEPLiMv~yY_-=B6mh>AaG1%AwhyJjuMF(AG z=&33PF1-RvY@d48=7mDUd-FX%o*syd#P8&$<0s-k78`K6van zt{8~N84iR)@3b85TEZ?&=i~7o0;;17_`EN5)oimQav-(@yWU%wT~(<70k2G~u47F-tt7LqLcwtmZ#?=bgSo;CMDDs#2h!baR$)1DAOFYT zKi)!!yMoc;LuIs1=>W+2)(VrilIB3MQV~1X=ft#L7%Z>_0F9-@_p!AfC3vHhaY6U_ zCJ1^hrUOui^W=V39|u>j8_q?u$qMPbF3=$Rt1`aH6A zxn+^oxNJWqdStbFT127w>>~YoIy-3N{#eFa*iQ^(>0+cutwa6!(c1ie!NJE-LJ~>1 zDnPbAa=dQu>KaP=X%yc>e-QKcc0-!xT34eA>AHiV$ zf8w2{5#1^4^zD5a#Jh3w_(YFr7F}+(%&`Gmi23@d22XO<-3rG}jOlo74Sh z@y_RjhK430za0M`RzbovZ0ru}s~^FXm;9xB0;VAX0ENQML=5x6Z)y_mjbhU8ok*Tb z8|%F;P@)O$YHL%|mxg=sw4mhMa?WC8phKrU3WH2-D0HE>CGoES^P-_-pXi| zmI{8jiQ>a=Fsf%8#M&I}n?SFmkjKfJG(WARYx$j_-m4PH^eYd*!VVitwu|=DiAmK* zKL&?T{WSWtTI*iF(U)mjUR^EVDWRsH$NEIX?O8r4IQZl7L+r@~Cg`DbhRG403$;h? zJzC|XKb;9QvA9_HXJpV$sMq6tbB2@boj2h+%42?x8-H!{)ElG<9-YOOHA)_wj{poh z&k?zB&dI>xe!l4>;;~~rq{}|5_feo@x{_HJSI_nBVtQT9FFHe&(1ZejZT}l6iOZB z_EsaKq0Fm5x4karbQI0sbY>J;1g#A(0n(!5DthX0x8v;sTcx?8-_nnNY~_|{%$Xfr zr;N^Bn9o_scw2s*u?I-uST5GTttQc9--8%V{Zc0@4eKjifRS;2*w@;avu67nN(Phi_`cIjtsZz{(t}R*~XhKIe(f{*}AR12BE_RtpL|qEU4U z-Pq*MmmYZ<Rpc2=V z|Mq@ehph$X?o%BZ#4j9eP3b9oNj@6#J(#>)C+hhvsH-APEg)d?i_-A#2w0hpFWE(c znqxQH>`fd^`gJ}^z`D&&p86>wIPGlo?#(z>M0yqL#Ga6iyCMX1^V`qUA$fG&@C4 zqNwu&3$`O!5o&0X8;~3T;%i{}tNN#O7`|WnPodHOc0sp>wd61^v zoxG4X0~XVz&SeHy1e3KpH?+wZZ=N_$)`@Keaxa1G=*l2ihIs+eDc&HvirkEw9k)r+PN@!t0aEY3byIspnXS6bN7dohRt%~|Nk)hopujk3 zkluM}vF?Z4Cfbi&I5nrZypnqbDDn!{2bcvo_VTc{m>DG$XWUL`KP*UYp2U9TR=fB> z&WngN_skDGCLakxdkMB`Lg=erYnYDbsj!MRI41P-KE2(Nw(QRAuxe{2jCi)_yl?D+QXLU#|S27uK*%w=skcvC>t zxsZB+Na(=R5s9Obf6x!r1TZPtbD>eC-hIqaIs-l*Lt`B(HMnB_{5Wp^;6M!|_j8wZ z4``-*`0haT$M)s=wdl;6(lfUnx2#haaw*5cs2R$xSWL4`Md&YJv6%jd%ElQ#=>y{6u2i& z#HH?m#=0w@Au9Zn1ejcCsk^Zm-iwYy&nrKr8uPWtsWn2j>{D zWxZ_{q62pZy{IIQ8uJv%5KQZf9#P5{_i)f-xIh&Lv_!*Su!ORKTeU*4BC}|~BA7Cp zFE8{cA8lb7S;uXQa6C_yHTv+glC%c&gkY4Ln_t``yk4tlWXNp{cP#QoMWr2ZZ0 z$~&MApeM>iwU}AIgsrOWcgzOWZc1vG2t%_Al3yO045mZjVaPxKJ0sbi8G!uVW@hGb z-y#zU;#miS;yGUSP8b2#bV>;2GGlSj9dk+y5+1DfP0ZMzGe{alll>0+oeugJy4B8Q zg9{nki*=CuWW8z50xY4j8{ggC517%Rk!kG==VPeo{i%abRxPtTA_=n~B>=cJXl6Rk ze_5j4q?L6E4QJ#;SxkL%1Y(4I(26Qn%*sV+3CUd>#E#}&NdOm(J{>1K zhFo|hR1(W`^?;7Rc>{z>FtO|iASj`Nxvk2$dr;ss)KJFkmGwd9SsLgoe7|w3g2Xp+ zVBNQFj%4wV6{;DZ>jFIQz?IuZ`+_pG^#Z-}2xYDB`7v2G=tYadz@}0^(;)jL96VX? z==;{{A*-OMY_^l7j&(f4vj(Hzyn+K)>CL5#LIFg0+cs*&skoiR#oai9U}v$yq?Myo zF?()kD#B?wt2o8wk?dP!T|AKV`Sa&kZ{}>}BEgk!;rc;<45kun0}WGIusj`-ePMC2 zxwVmL0&GPdll6;3J%Bi|- zVWLNh&8;$y+vfSn3EO5T8Xc~1g|zkOAKb|WzrA1$5r-;b|7B)S}Y zwmrQc4Knap;Fy?cZ}*Reoc#+xg_qgt)Rx`x1ew_4)Iw>5y*OdWjNy%f*Y&lV+x#o2 znF8J4SQ4r`=UxOssS9!nB6n2^%;I8=Je@m}LXfld8fy050|{DX1Gx`Vly`o+Z>PV5 z4|Za$P9L5@c2oE%L7gLJTL5UiC*A-#%&TDxvlsB{Q~Pp}k&hjf?h2c|P0L>(eL)Fz zprU%X4JhMOtGbBF4^?a-=?tI&A26imy_)(@+>r`RMObr|zaFoiMI?(N*ke?b zE=~Pv5VELybJ6+SI(x=Y=hte0;^zJv+g~xqpq{vKF%PEV442!@wUf$2) zgTLdowl@UvmR1=)?B{?aW%f^tEE5#?Z9akZSNDwPkn!A}k0YBh!mfThpI(DWrAvR1 zsGLc(=a$d_cU3)7jEY&6uJCkgMe@_4s6hXIEYPXg@&t^ zU~@dp59GJkcS8$~w^dgL90YcEQ=I1Js*LMq6u$$&B%;zS8UO_v3^oKK^-5|`FMG}6 z%zO8E&BWbYVM`ib%uJ_TI_M0b2+OHL*|F{eTU2Cb%eODh^}UL@ouf2+t=H$Oa>oUr zrh#OFUd!IjTu1=Cah>8S>z$#sLkn$#^M0gI!F76ki>+D}&pg47#;ko;&3e0Jy2@|# z<4gwB;Q95=JlvuUKaQ`4vOrHXCmd|zMxaGt(PbhzS*{S&tVIhtEc{VQZ7fF@ZK#P( z9*>5qA`l0S1@5tIZk?EL*o@PTU{tAry+)0F9E1p@DzK<;MqZxol*sCds2dudw}R+j z1H~QKWpQ%cLnJs~0M(Y&eJUOsMZ5fJ?euqvqJ}UEl^+iw?e2NL(X}~ zM>mAdT)y-(GCSw6ISbSPZII>gId^xK_jN%LmIW7T@_Ltp(w7Yi+dAlbT3Dj3Nmg#8 zdhxlc2?D?lAM~dA10o3u!-@K%*Q8*V4<^oR={frrsW&K^Wpk3n`ERf<24W0EnhFPS z9bWLjDbQ|YJQJR0_ZJG$0VR{a9$O!h2V|Z+X1SvgumOZLQKTQo6ohn66&Rk@L5;Ut zFTeJnqJYqHWkRuPf$Rir zIj90tRmdpt~AXv1yfYS7Qxt%Qm?Xnu-f4 z9gC~H3*{i+ltCZJ3u;Ahy!$v)nkq=-(1XCPugr6iW@Dft;auPb0VR>mLpUTB z0~)U3T4M_c;;^5M$*nxw*#OuSgtvkHB*(|YyB4g;z?Bg2pdVbb{I1wapzX7cjMilf z@~(~krC5tJNe&RcX<#*il#~gY=9sZ1)lPiB{LX#WCqX+7>HF`nMu^ok;S zUOhywJv=<{0E|+7xRnFaVGO%Pa{kInwpl=AOat3MzMYMN29xw%}x}db>xGgUKk=^8XaLq1QX^}3=@6jc-DxX91Vgc=Y3!`=xv`8m% zcO14SRYq!7Lon^ft}d@QH^00NA{Nr22_XybFd9sV;i}+sUL)a@CrMb#Uu+8o+CV+> z$3&VZ2Vk39HX6LP`wr`>N=0kacN{eG(AEv=n6?s_Gc}KhAekb_`i`93Y9iwGRwR4H z0Eqd>0h7H#ld;i~L2y)=-czc~5G`V7QX8O=iV^lcW`y9KkE70$wKud^gt}EM3B1Rm zPy*z`jL$8knpwN>AZ=Vl@u65LMSVl3ea;hmR=TUX+IN*0A3K&~-&apcGL8aiHhp4$ z0Kpp$>iHV*?#vT4AMSCmy{_i(e>X#Fp8ol>$Kz+m=s|Y?dA3-N1Dk$#9J1OUdm02|!Q6gaw!8S41IRloaGDpv zU;n>AXn6(NcMzFs=LkS?JSjexzfO07A{31ag68`Z)-Muw+ylL(20_gxkxXI|u&lZB zqSXF9DjL^0`&!?jXaC8})XRegAlu^flgj>ZpwfJ)BBQ866LJF|WP@W#@G`FR92f>v zQ?5&f6_8PRZhlMf6?L$jKR&~X0p@OeKr0{2q|eGveSa{f3s<9h9C;X#ii*g0--XY< zJTGZ;mmYLtdB_x(IdD?PSvYi3C!U;2n&z=(3&)BT+A%|1YqiQ0;=xhUPOsJx)cs2^ zpU$WBbdrPG2Pj)=@P_CHRRSK`YwGpnRCpSHB}#sJbQPK3ARcU9;o=BUf1TD8U~jv! z6U2Sf5SF^7cp3D8gBzBZ98Fmk&M`{d#4^3q=%8`z{Cg7bjAwxanYs3Z2-bK-6-iz= z7RG9@%T375pxils&D8S{iMv|`m9EXm8`nTHEWz*TLuAWLKW!-MoubD*n6OOKAY~Wds>%Y?mP@N8885$G zOf}~cTuzwJMJ9#eU**Ui!8(plGh=XCvYjRVb#WT+vEv=GFkAcPC>a!3CT&VLTKvuG z5-f^kz23m9k8<7b$sO;PJs1Q_3@HY?J+i|vSbpA@)VmWQPxz_LzNVH_-F1ro;xusZ z)P$md2+nJL@XOi=Z#ABJJ#Ncd{cj8zAgHR`)P0-326*)_8qYf)AEjhAJ{nV=glw{S z_{wkJusC5d>OJOO`4j6W<0?zm;!UH^u1X9ND` zl24SG7iQzgbSIdz#Qif#BFeU=3N2&2IEEgbt$)3uPMN1+pShpA;w$>EmImHGZC$a} z4KG!k?uWsCDze9-c8DH)k}EEtZm53b&7ypKPlM5U7WZ%AtIFS60$@UwgT>ga9%z?N z2psKk^_cUdf{(7>M?3+)K1D0(YYV#4GDuMu`1??`5bqb~DAcrsTn=X)Yj zsp%QJg>C#8vbupE->gSd9m4?aNnpB$3s;_`}>-6pi{KGgyV@4^9GfAZd zf9}W~QI+{Kb?*tRvm2GxnNwK@G}x|g5*J!3@xh4CB~R1g`uDaOy@4FR@^yu{xZm4 z&%Q2s{QikL7n*iArTtvoJ0;i~-yAB#tZ}7cmj3cdk9wP$>HL1HDQ3g?QYq13Ap5L@ zg$KGSM#g)8w$kHt{>%rd?&~x=_JWIz=}LK-ch4D9@+YertF)X6NA?1GH$(809-}m- z+?A44UEt5cVcw0Y&a`UTemP(F@eU8-A~2Akz$O&zMzDLd7-H*tYyH-8*h zU^dny%Ie)zQmrGFY6D%=l_3U7pMY+abX5>;ukyO7_X(Ftr(;fPje%*!Zp1+V*+b@Y zHxwAvGizLb=k{L|%jO@yTs+_+giJj4Fn%;A8+lcTq&zs$@f5I=D$-R;5SkThz4SI| zxyT*>MwX2zE?j2l^`QKXSQR)b<{8JHert*bJHdOoh*`Zoxkvy64h?-lvwmqX?eDR* zv%D*dssqORE1l0&v0yf=I9zD47 zoL1O!deY3OCtKwAl02$Vs%dA#z5B%+OE>7T4`Sq7ZkBaK4FP0~% zJ4(jxpA7d~;V`DWPqbX94nP?2Z)rb)Suup4y)d5`XzgH+Ixf6>LVO!8@^l_lM^OsT z+nxtRk0|Q1>RFGED#(@}i4nHkLxEM$zEjLbU!{C}w0k0Dg9a#7dR+=aXUzcSv8NO} znp}*3FK6XkCyqlxOVy84=w&-f%<*Aw($Guyd|0b8Ai;BA^_CS1n z4GR7n*BryyK4YA2;;-3-FY7BdUm9lCZr_W?BNW-7(?)}dV&?KGtN*mjjVedIb^oa+ zZ*)jn`ABm}N9H54HwO}Ik);EfkYz|wr_k>`9qc(`FSKgBBm^;dW2ogY540>KlZ!RZeWS;3{_mHJp6zL z?p5{@P3#m^fD;PvP@FlHp(Ei`lYz#{0Y-5A*W>*)y_|qU7BNfME)fb_zPhH95Bu_2 zSI*_{d9T25Eby#12wNJ5OmwyAA`i<5R-x#F9|+NyDaKFfv=O{)%y%b7#oNP*IQBd_ zuwZh-(qap^U2F`wVes1tksOp5)Sl?$sefTeYWJW=iTbK%n?PLY=MQ75&m_eS?|&Ly z3lanZ)y-RaVuPQZZ_Aa@ z8E1o4`pU)F`y}yC?_WTPY`#R8o%lu;R4(65nSk|4ZPq znpb#Hr14!DVQ4TuV>Nxm>i(*ezv&hYgy^HvUfX!bBoE$`AWCXl4q+O4t7Vz*p%KAJ&f&jLms%QIlKcn4NW>X?q&?kOrnx=nOnclXPLXpEIUg$F&T z^CuwOp4A%v(n5<_Dn~m3+AoldDL8u|Dm!9Ao`bz66Tt1H@oxnJ>0M`YDeO0L>=toqI_n%h{2E=m!}_-ufRu z1^OSt=I244tLY9aYNgcXt_(@!0Uffu>>VSI`5og@L0E#o@iNZ*un-;TGl2?4E zFAn26&#{?xAmVeowXRn9Yidg|S$eGTtlw~w>oj6H-|~UXLL^bgvvoIxV<}o$+#wZ| zf@KE72f@Y}*ffUU`L(BB#9E3$)AmLqB6uhT_Z91usQwU`g!k){L%#we9L zQU|yH8f@y}YW(6@!DH%8;jdHaZUc1(I3UqAMs|33jFY!j6<@X3S^jP>4q9+!WZ;b} znds#~toUPC`?QhNnoN51 z8n;J^&TMYz4cDK#d{d9zp7dRLQHnc>QZNE*>^o?h z1N=Ul&vTj>kbHktxc{^3Edyar{W$ZOQ>VxDs`}1M(iNV}!U%7>?O&Ogz!ASpLzK#2 zF!*yz!Q7$0#01vZ;x;spX(1{yt!(mU#R*;23ay8MQ+A6gA<0Nrl z*<6Tb+Qj!_u&q@7;rnHjyI}SZsfg2o=m!99Mk~5uF1QG9)5}$!y zxXV_vhnDb&6{ZY?qN(5`=2wN`^8$%JGvRb!pd(|Yu&fW;=0JtGiIa^ zx3x%o^x0BSqM`E{FWOJM>7fTmu=*=xd{RyEWla{}J^SiZS*>bU+vw6=%Yu>U>hsSL z!K&P1r}EnXhc=IQg(T0I{vHK8$m;aE>~IX_*AYF6CPp#O?ELpRJEt2A%+Qq^d6v}S z8pSN3Rd1ww?rr`0DBI3t!C>c$(Lhs4gFF2YT>8#-^Cb;@gG$vIr43eTO}b8H=0_Zr zY&5sh5}(ZRa+#z{<0#yrAoYf39RrR=8MNDYa>fF;=-PF$p158%3lHQ8x1=PAC>2%| z>``3s#NTzAEpD))S!Y39cHcBGuahA#;pgyH9Xh#6_GPP!H`Z(3+y0kbtiJ@+6^>&n z{^(Kq#`e)oNt}xgS{+;m3qGjny?L%jdV=3^yxP@#Zf?B5jPY9cV7cew%{kdsh+sQ` zXCWeDMb@1H4xl7eAmnj#Fock178W@G7m{9(Vv$HdAbZ3Ded^f98~;#n_EJ!gu|We4 z8K+y)&u{H?ZldKw85JaEafLPO@hBZ@5KUmfdk}yO;003t?fb26?f;Rwf$R$X7CK`J zy};~3umAb+f2D4nUpi*y8UZB<9jnaNO-XNx`O4=h{no1L)9-GGs}|f;PwSpG?XFzJ?B9$JXcEC9>W*1z1}nkWehUpa5e0uF=Sxs^eu7 z`12v{1z?dO%Z3_ET&2OG;50Wm2!|HJOj`qrxU;j1oVV(RqNV2cQddg=Z+76?tck4` zguPj~W~&vI3hv5$1sz7s4v{NbjR(VLY3gf;nRRjf?p1B0%P_iQM^w35%c%ijt*qg5 z#ovyHXhNW~rvRugyBGXOSbdrkyl!d*&XL;`zEz<{Bg&b15- zA#-qQ7NTP4c9=`Oyn#NjMVd4RsPMK)^?)N2OzxW<{?!0yc6XW}so?0>fk}Y*Hy_*` z#T*PUq|O$f^KzOCi51cUDCbC#Jr+RX)(<%~NyD9}SJQWvfeUAeZ;H9Rt6SF(Qv-6GaIx%c zh;w5&uOj(ArqX=;TSx*lhIYJhrGX2nm;fIj2SEObcCZ2dp5(omZRMFPc{CoZ<3essgCibW`zonT`*W(e{AV}R0?W6XUf;Ehaus09gBuz^3zLA+zqivon8|NP8ZM#tXV?8&WqI*S(>DgA}td&8}$4 z$Da@6nUL$N8)W#P)3P(K++6Iw+Db=C!riba3X7SAObWi zf~>b_GXxy{@O)jfiv|07toR*p8IXSg0RiX&acGW-4w_1;-8j|2A>;Sl1gAi{hzMNh z>~+|_D$QTH{`cyz`Zb_*WIQfVNv2~{zXIvn;qsW|RgDd@&0a_XF;uk)0A5a`Q}who z(17sqJ5 z10XV}4s+J=KK*jgc+=QSG6J- zRnx>=bKHMNtE!d|c>ts< zqis?vIe^@BpkR>$%B3}s#UR-qq@n`L*a8ShA^Ay^SFfr|K&0F8*#hQ~Aee*Xkd;>T z6HB0Olm~~fiGzEfv2by7R?ou|wFQLbZ#V9Z5%_SmET5)oYk z!II|?k-j}$tP8GEX(YQda>R?qsYC_67KUZXrW;rC%4Op$s zyOl+}ythK+SJ4k-OOa-68bB8$FueB=2sE{#3D*yE=hm;wx2fRJitA1Z-kwOY7Lsvw zPU0+t2zSJAn#o-3^$c`KAIMX{T=R8D>;T0m#9D$e0oKPDM}3MmwPL3$Uh`~$c(a9E zOKDcel)IYZqRCZM@H!EaN`O=j9leLXDWG1CKl4ftS$Z);SkRD5S5Th`{^+=FQ2uYF zPjzV#Yf?ZC=w7P@4uv%9O@l8lFP9e=Qk=^61 zqhIBgmtQd-x%@Z{S)udl;D_u5;@E=EcT#pYPjS8+js6`NZS(YeUjUSN>xFXyu}ATc zCJ%&U1m&`JRW9K4%m>`rITKF|dBa?#T~`LIQQZa7L7Et7|Kknx+Ft!&L748vRp8GQ zWHfI=sR2rNkn}ruXwLld`yarO!)n^LfF#vTaNh)QUFi@B*^v0=z#yG|qr>kf;J|0x zrPa&c0a1y0Uw$8yr#r9L#kuNZPfe`?p|k{)4^V<-*6CL5UMkv{Tf_n1L6INV73Bc< z5z6%pvOY-LWPEd&QpQrx?idF|ha;fXqRQ8R!o9_tLk?8V?cgkir#%Xg+VR_07eEa% zT-ju&*AnFsF6xzIY(W9CM{)l-0XFghq^!x&I}tAhQUyR~hdsXESRztm^yn=q`#L23 z)dGZeQEZ!44p5sxL8(*yD{p{>KjpYb7!T0NEll4>KuxQ-zC3y6yD6J+`R(@+pXjl> zE+m@*lBeO5A7~@XpQr)bMh*n#zP+(KO;eq`o{EU!#DxUO%c;m33Xl+qy^hagcc5bd z{?YuS>jyuLHfk^+-5VsABB2l-DQKhckKg+SeYwKIzfj7am{*#BURT=^w((XG|A z5Sq&XoR=T&C^#MfX^eUn; zR^SKBszGWFAi+&|#jQ{lX7%QY52);4$2``4)d z{iXCM+$iQ_hvwJz%1CS-e@4;ov31`W;bF8yqCcsWv==pn^|dLAt&@Hr`0$Cw+P@C; zS6*G8dexiMuXgj4yei*w6C_==?LP77a|X<5FVD`7$(dKFOHd^EJ_f(%oFmsWeACR5 zl8UoFu(8#lraTC$pHW^)_2+Qc)eN zep@#aS;6C!N5pNNXE~QJj5w-M-b}hrd>Z?A>x4Q>b>^F9sZ(sLbWDCUkR#83x8?Pq zm1WI|%xdzC&_V4K7)~tuz^uJI`oy{~m?`FX@5wg5on{F^!QKR7e>dqhXQ1iAxvb9h z@)*4uxwe#G{AP6}Dalcofhv4hU>MHZY#L17!y=Qsk#HW3bGaTB)diu5L<`1=PZV~28) z7MGB(u@-D~j1i2Q4#Eha3HIm9z2d!A&)U@B=cX>>Bd5zji%6P~5&u9pX zh{^R&us5t9MO~P<*D$E$BvIYWrs<;Uj_Nqir2t`q>1-g~#(~3gPOrqc4-Gfv7ImxP z;bmSu=mOK3Sz0;4FGT|&$GC0%khKzW;XBz{9o1>Hax=eC57H>>CJNl~C72PD!K}L= zb@V6?!SpO)nGwy>MIEfR`-#q!^N&i3LGOK{mW2-*nH43R*PR-UaBTaQWJr_se`@>g zsHV1VUu+;E;yHjQ(o~9crAkLZF!YY0sz@;OjnYcpY+_ah153uPC5mHy{(9QjHKSRPi;9*=S2d-_&1Hbe9h^wQ z4yxF&&&tbgo}(>#s?Go!2*HfOZ||Na?4{*NJaEKnqCuY-f8PWmK@- zJKB}#7yLsMNYb*mv~GyYR>QB1RHL3%1^8EDQ8rmM!GV=8NHVOqUq*)MsBBg=^MSw( zm{=6IwJ6TVq__L?zUKtnzKDD`aq9IodLb)yCAy2o{ioW16c&2YM473r%VT6pqBd2= z_SeKaw+4`IOOa|GbqR=NicCab)2GsP>*|IPl1gTf9-PHt|H~S_(K=rd)-qOd;ZktD zZDP@|JHyseb+f@A=<*GbeBk9GgOdr~%5va9U+14cxnmbqBAW-ZYL4VTxLdV9i1L~_ zjgI^D;Nidol+U(Fxc*%ffi!l!Z?1yM1ZM<~x(qvw_#7wzuVcdc#yAChb*IXwegso? zcS#JAu{&SGyHxMSR3nyfMI4Oy`PIz`gR2|?#@+F;v%f*!aN2�C%kp?H(kxB~H1z!EIB2#qezT$+2+JUdO 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 h)NlR&KU$4PU>{|n%iIne+B literal 27968 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
      `w5i#B{H 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 diff --git a/versions/raml-10/raml-10.md b/versions/raml-10/raml-10.md index 21b77db6..0b748d25 100644 --- a/versions/raml-10/raml-10.md +++ b/versions/raml-10/raml-10.md @@ -397,18 +397,20 @@ The RAML type system borrows from object oriented programming languages such as RAML Types in a nutshell: -- Types are similar to Java classes - - But borrow additional features from JSON Schema, XSD, and more expressive object oriented languages -- You can define Types that inherit from other Types - - Multiple inheritance is allowed -- Types are split into four families: scalars, objects, externals and arrays -- Types can define two types of members: properties and facets. Both are inherited - - Properties are regular object oriented properties - - Facets are special "configurations" that let you specialize types based on characteristics of their values. - For example: minLength, maxLength -- Only object types can declare properties. But all types can declare facets -- The way you specialize a scalar type is by implementing facets ( giving already defined facets a concrete value ) -- The way you specialize an object type is by defining properties +- Types are similar to Java classes. + - Types borrow additional features from JSON Schema, XSD, and more expressive object oriented languages. +- You can define types that inherit from other types. + - Multiple inheritance is allowed. +- Types are split into four families: external, object, array, and scalar. +- Types can define two types of members: properties and facets. Both are inherited. + - Properties are regular, object oriented properties. + - Facets are special _configurations_. You specialize types based on characteristics of facet values. + Examples: minLength, maxLength +- Only object types can declare properties. All types can declare facets. +- To specialize a scalar type, you implement facets, giving already defined facets a concrete value. +- To specialize an object type, you define properties. + +The following diagram shows the type families and examples of these custom types: an object family member Person and a scalar family member phone. ![Types Hierarchy](images/typesHierarchy.png) From d65767cfbe60de40c28651b9832d40eb7b6b7235 Mon Sep 17 00:00:00 2001 From: krishahn Date: Sat, 16 Apr 2016 23:05:41 -0700 Subject: [PATCH 101/241] restore whitespace width-wise --- versions/raml-10/images/typesHierarchy.png | Bin 31303 -> 32859 bytes 1 file changed, 0 insertions(+), 0 deletions(-) diff --git a/versions/raml-10/images/typesHierarchy.png b/versions/raml-10/images/typesHierarchy.png index c702b380de32ff2b6dd1fc8dc8f88055f8c5add7..234f38f700a2ec1a4a474a00c07561ccdf836b21 100644 GIT binary patch literal 32859 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 `yyGD7#| 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 NeW>}M_}y@ literal 31303 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�C%kp?H(kxB~H1z!EIB2#qezT$+2+JUdO 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 h)NlR&KU$4PU>{|n%iIne+B From 4aac780bef65896699e4bf20a2d06e35b3bb5035 Mon Sep 17 00:00:00 2001 From: Christian Vogel Date: Sun, 17 Apr 2016 11:44:37 +0100 Subject: [PATCH 102/241] lower-cased forbidden and without since they are not mentioned as upper-cased key words. --- versions/raml-10/raml-10.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/versions/raml-10/raml-10.md b/versions/raml-10/raml-10.md index 8001c15d..e1df43f4 100644 --- a/versions/raml-10/raml-10.md +++ b/versions/raml-10/raml-10.md @@ -1671,9 +1671,9 @@ https://api.github.com/users/{userId}/keys https://api.github.com/users/{userId}/keys/{keyId} ``` -A RAML processor MUST NOT allow one of the computed absolute URIs to be identical to another one, WITHOUT consideration to the possible values of any URI parameter. +A RAML processor MUST NOT allow one of the computed absolute URIs to be identical to another one, without consideration to the possible values of any URI parameter. -This example would be FORBIDDEN. +The following example would be forbidden. ```yaml /users: From 083dce530f3ee3e589a5a0bf97a58242117c324d Mon Sep 17 00:00:00 2001 From: Christian Vogel Date: Sun, 17 Apr 2016 13:07:36 +0100 Subject: [PATCH 103/241] some smaller changes --- versions/raml-10/raml-10.md | 31 +++++++++++++++---------------- 1 file changed, 15 insertions(+), 16 deletions(-) diff --git a/versions/raml-10/raml-10.md b/versions/raml-10/raml-10.md index 0f55909a..8881214f 100644 --- a/versions/raml-10/raml-10.md +++ b/versions/raml-10/raml-10.md @@ -416,8 +416,7 @@ The following diagram shows the type families and examples of these custom types ### Type Declarations -Types may be declared inline, wherever the API expects data, or in an OPTIONAL **types** property at the root of the API -or in an included library. The value is a map where each key represents the name of the type and its value is a type declaration. +Types may be declared inline, wherever the API expects data, or in an OPTIONAL **types** property at the root of the API or in an included library. The value is a map where each key represents the name of the type and its value is a type declaration. ```yaml types: @@ -490,7 +489,7 @@ types: #### Property Declarations -Properties of object types are defined using the OPTIONAL **properties** property. The value of the properties property is called a "properties declaration" in this spec. It is an object whose property names specify the allowed property names of the type being declared, and whose property values are either names of types or inline type declarations. +Properties of object types are defined using the OPTIONAL **properties** property. The value of the properties property is called a "properties declaration" in the RAML Specification. It is a map where each key represents the name of a property allowed to be declared for a type instance, and its value either a name of a type or an inline type declaration. In addition to the properties available in normal type declarations, properties can specify whether they are required or not. @@ -776,8 +775,8 @@ Array Types are declared by either using the array qualifier `[]` at the end of |:----------|:----------| | uniqueItems? | Boolean value that indicates if items in the array MUST be unique. | items? | Indicates what type all items in the array inherit from. Can be a reference to an existing type or an inline [type declaration](#type-declaration) -| minItems? | Minimum amount of items in array. Value MUST be equal or greater than 0. Defaults to 0. -| maxItems? | Maximum amount of items in array. Value MUST be equal or greater than 0. Defaults to 2147483647. +| minItems? | Minimum amount of items in array. Value MUST be equal or greater than 0.

      **Default:** `0`. +| maxItems? | Maximum amount of items in array. Value MUST be equal or greater than 0.

      **Default:** `2147483647`. So following are both valid examples: @@ -830,8 +829,8 @@ A JSON string with the following additional facets: |Property Name | Description | |:--------|:------------| | pattern? | Regular expression that this string should pass. -| minLength? | Minimum length of the string. Value MUST be equal or greater than 0. Defaults to 0 -| maxLength? | Maximum length of the string. Value MUST be equal or greater than 0. Defaults to 2147483647 +| minLength? | Minimum length of the string. Value MUST be equal or greater than 0.

      **Default:** `0` +| maxLength? | Maximum length of the string. Value MUST be equal or greater than 0.

      **Default:** `2147483647` Example: @@ -930,9 +929,9 @@ The ​**file**​ type can be used to constrain the content to send through for |Property Name | Description | |:--------|:------------| -| fileTypes? | List of valid content-types for the file. The file type `*/*`` should be a valid value. -| minLength? | Specifies the parameter value's minimum number of bytes. Value MUST be equal or greater than 0. Defaults to 0 -| maxLength? | Specifies the parameter value's maximum number of bytes. Value MUST be equal or greater than 0. Defaults to 2147483647 +| fileTypes? | List of valid content-types for the file. The file type `*/*` should be a valid value. +| minLength? | Specifies the parameter value's minimum number of bytes. Value MUST be equal or greater than 0.

      **Default:** `0` +| maxLength? | Specifies the parameter value's maximum number of bytes. Value MUST be equal or greater than 0.

      **Default:** `2147483647` #### Enums @@ -1051,8 +1050,8 @@ The simplest Type Expression is just the name of a type. But Type expressions al | `Person[]` | An array of Person objects | `string[]` | An array of string scalars | `string[][]` | A bi-dimensional array of string scalars -| `string \| Person` | Union type made of members of string OR Person -| `(string \| Person)[]` | An array of the above type +| `string | Person` | Union type made of members of string OR Person +| `(string | Person)[]` | An array of the above type Type Expressions can be used wherever a Type is expected: @@ -1209,7 +1208,7 @@ MyType: type: ParentTypeExpression ``` -Depending on the value of ParentTypeExpression, though, the meaning of inheritance will change. It is important to understand the differences: +Depending on the value of `ParentTypeExpression`, though, the meaning of inheritance will change. It is important to understand the differences: ```yaml #%RAML 1.0 @@ -1285,7 +1284,7 @@ types: Each Inheritance type is explained in detail in the following sections: -#### Object Type Inheritance +#### Object Type Specialization Object inheritance works like normal Object Oriented inheritance. A subtype inherits all the properties of its parent type. @@ -1303,8 +1302,8 @@ types: Subtypes can override properties defined in parent types. There are two restrictions: -If a property is required in the parent, it cannot be made optional in the subtype -The type of an already defined property can only be changed to a narrower type ( a type that specializes the parent type ) +1) If a property is required in the parent, it cannot be made optional in the subtype +2) The type of an already defined property can only be changed to a narrower type ( a type that specializes the parent type ) ##### Multiple Inheritance From 2c2456e5706e93291d76ea7f781895dc0c561282 Mon Sep 17 00:00:00 2001 From: Christian Vogel Date: Sun, 17 Apr 2016 13:10:58 +0100 Subject: [PATCH 104/241] removed unnecessary chapter --- versions/raml-10/raml-10.md | 6 ++---- 1 file changed, 2 insertions(+), 4 deletions(-) diff --git a/versions/raml-10/raml-10.md b/versions/raml-10/raml-10.md index 8881214f..e6c8e047 100644 --- a/versions/raml-10/raml-10.md +++ b/versions/raml-10/raml-10.md @@ -1302,8 +1302,8 @@ types: Subtypes can override properties defined in parent types. There are two restrictions: -1) If a property is required in the parent, it cannot be made optional in the subtype -2) The type of an already defined property can only be changed to a narrower type ( a type that specializes the parent type ) +* If a property is required in the parent, it cannot be made optional in the subtype +* The type of an already defined property can only be changed to a narrower type ( a type that specializes the parent type ) ##### Multiple Inheritance @@ -1323,8 +1323,6 @@ types: Note: Multiple inheritance is only allowed if all Type Expressions are simple object Types. See [Inheritance Restrictions](#inheritance-restrictions). -##### Property Overrides - If multiple parent types define a property with the same name: * The property will be required if at least one of the declarations are required From 6ca9871fcff420eb5b443b5653ba32e7785ed437 Mon Sep 17 00:00:00 2001 From: krishahn Date: Sun, 17 Apr 2016 05:34:59 -0700 Subject: [PATCH 105/241] review changes --- versions/raml-10/raml-10.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/versions/raml-10/raml-10.md b/versions/raml-10/raml-10.md index d35525d3..5e222474 100644 --- a/versions/raml-10/raml-10.md +++ b/versions/raml-10/raml-10.md @@ -253,7 +253,7 @@ baseUri: https://na1.salesforce.com/services/data/{version}/chatter Specifying the OPTIONAL **mediaType** property sets the default for return by API requests having a body and for the expected responses. You do not need to specify the media type within every body definition. -The value of the mediaType property MUST be a sequence of type name strings or a single type name string. The mediatype applies to requests having a body, the expected responses, and examples using the same sequence of type name strings. Each value needs to conform to the media type specification in [RFC6838](https://tools.ietf.org/html/rfc6838). +The value of the mediaType property MUST be a sequence of media type strings or a single media type string. The media type applies to requests having a body, the expected responses, and examples using the same sequence of media type strings. Each value needs to conform to the media type specification in [RFC6838](https://tools.ietf.org/html/rfc6838). This example shows a RAML snippet for an API that accepts and returns a JSON-formatted body. If the remainder of this API specification does not explicitly specify another media type, this API accepts and returns only JSON-formatted bodies. From ed3729f73c9366bd8e20ff4f2ad964176909d18f Mon Sep 17 00:00:00 2001 From: Christian Vogel Date: Sun, 17 Apr 2016 20:44:02 +0100 Subject: [PATCH 106/241] some last wordsmithing --- versions/raml-10/raml-10.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/versions/raml-10/raml-10.md b/versions/raml-10/raml-10.md index e1df43f4..843545e9 100644 --- a/versions/raml-10/raml-10.md +++ b/versions/raml-10/raml-10.md @@ -1622,7 +1622,7 @@ baseUri: https://api.github.com The key of a resource property, i.e. its relative URI, MAY consist of multiple URI path fragments separated by slashes; e.g. /bom/items may indicate the collection of items in a bill of materials as a single resource. However, if the individual URI path fragments are themselves resources, the API definition SHOULD use nested resources to describe this structure; e.g. if /bom is itself a resource then /items should be a nested resource of /bom, vs using /bom/items as a non-nested resource. -Absolute URIs are not explicitly specified. They are computed by appending the relative URI of the top-level resource, and then successively appending the relative URI values for each nested resource until the target resource is reached. If, and only if, a baseUri has been defined, each relative URI of the top-level resource needs to start with the base URI. +Absolute URIs are not explicitly specified. They are computed by appending the relative URI of the top-level resource, and then successively appending the relative URI values for each nested resource until the target resource is reached. If and only if the baseUri is defined, the baseUri is appended to the first segment, which represents the top-level resource, of relative URIs. Taking the previous example, the absolute URI of the public gists resource is formed as follows. From 769fd371cb477fc4069ce7762cabdc6beaec79fe Mon Sep 17 00:00:00 2001 From: krishahn Date: Sun, 17 Apr 2016 18:51:21 -0700 Subject: [PATCH 107/241] Object Types copyedits --- versions/raml-10/raml-10.md | 12 ++++++------ 1 file changed, 6 insertions(+), 6 deletions(-) diff --git a/versions/raml-10/raml-10.md b/versions/raml-10/raml-10.md index 2833dee3..6f746072 100644 --- a/versions/raml-10/raml-10.md +++ b/versions/raml-10/raml-10.md @@ -462,18 +462,18 @@ It is recommended to use the `type` property instead of `schema`, as the `schema ### Object Types -All types that have the built-in object type at the root of their inheritance tree may use the following properties in their type declarations. +All types that have the built-in object type at the root of their inheritance tree can use the following properties in their type declarations: | Property | Description | |:----------|:----------| -| properties? | The properties that instances of this type may or must have. See section [Properties Declarations](#property-declarations) for more information. +| properties? | The [properties](#property-declarations) that instances of this type can or must have. | minProperties? | The minimum number of properties allowed for instances of this type. | maxProperties? | The maximum number of properties allowed for instances of this type. -| additionalProperties? | Boolean that indicates if an object instance has additional properties. See section [Additional Properties](#additional-properties) for more information.

      **Default:** `true` -| discriminator? | You may use the `discriminator` property to be able to discriminate the concrete type of an individual object at runtime when, for example, payloads contain ambiguous types (achieved via unions or inheritance). The value must correspond to a name of one of the `properties` that are defined inside a type declaration. The `discriminator` property can not be defined for inline type declarations and should only be used for scalar-valued properties. See section [Using Discriminator](#using-discriminator) for more information. -| discriminatorValue? | You may use the `discriminatorValue` property if a type also defined the `discriminator` property. The value of this property should be a valid value of the property with the name equal to the value of the `discriminator` property; and its being used to identify the declaring type. This value should be unique in the hierarchy of the type. The `discriminatorValue` property can not be defined for inline type declarations. See section [Using Discriminator](#using-discriminator) for more information.

      **Default:** the name of the type where the discriminator is applied to +| additionalProperties? | A Boolean that indicates if an object instance has [additional properties](#additional-properties).

      **Default:** `true` +| discriminator? | Determines the concrete type of an individual object at runtime when, for example, payloads contain ambiguous types due to unions or inheritance. The value must match the name of one of the declared `properties` of a type. Unsupported practices are inline type declarations and [using `discriminator`](#using-discriminator) with non-scalar properties. +| discriminatorValue? | Identifies the declaring type. Requires including a `discriminator` property in the type declaration. A valid value is an actual value that might identify the type of an individual object and is unique in the hierarchy of the type. Inline type declarations are not supported.

      **Default:** The name of the type -An object type is created by explicitly inheriting from the built-in type object: +An object type is created by explicit inheritance from the built-in type object: ```yaml #%RAML 1.0 From 3d2e9028504e6654fbdeafd7e0fc430416db95a7 Mon Sep 17 00:00:00 2001 From: krishahn Date: Sun, 17 Apr 2016 21:30:35 -0700 Subject: [PATCH 108/241] edits of Property Declarations --- versions/raml-10/raml-10.md | 16 ++++++++-------- 1 file changed, 8 insertions(+), 8 deletions(-) diff --git a/versions/raml-10/raml-10.md b/versions/raml-10/raml-10.md index 2833dee3..c8acd226 100644 --- a/versions/raml-10/raml-10.md +++ b/versions/raml-10/raml-10.md @@ -489,15 +489,15 @@ types: #### Property Declarations -Properties of object types are defined using the OPTIONAL **properties** property. The value of the properties property is called a "properties declaration" in the RAML Specification. It is a map where each key represents the name of a property allowed to be declared for a type instance, and its value either a name of a type or an inline type declaration. +Properties of object types are defined using the OPTIONAL **properties** property. The RAML Specification calls the value of the properties property a "properties declaration". The properties declaration is a map of keys and values. The keys are valid property names for declaring a type instance. The values are either a name of a type or an inline type declaration. -In addition to the properties available in normal type declarations, properties can specify whether they are required or not. +The properties declaration can specify whether a property is required or optional. | Property | Description | |:----------|:----------| -| required? | Sets if property is optional or not.

      **Default:** `true`. +| required? | Specifies that the property is required or not.

      **Default:** `true`. -The following example declares an object type with two properties: +The following example declares an object type having two properties: ```yaml types: @@ -511,7 +511,7 @@ types: type: number ``` -In order to achieve a more "object oriented" experience, a series of shortcuts are available (see [Shortcuts and Syntactic Sugar](#shortcuts-and-syntactic-sugar)). The example below shows a common idiom: +The following example shows a common idiom: ```yaml types: @@ -526,7 +526,7 @@ types: # required: false ``` -Furthermore, when the `required` facet on a property is specified explicitly in a type declaration, any question mark in its property name is treated as part of the property name rather than as an indicator that the property is optional. +When the `required` facet on a property is specified explicitly in a type declaration, any question mark in its property name is treated as part of the property name rather than as an indicator that the property is optional. For example, in @@ -538,7 +538,7 @@ types: required: true ``` -the `profile` type has a property whose name is `preference?` (including the trailing question mark) and that is required. The same property could be made optional in two equivalent ways: +The `profile` type has a property named `preference?` that includes the trailing question mark. The following snippets show two ways of making `preference?` optional: ```yaml types: @@ -559,7 +559,7 @@ types: Note: -When an Object Type does not contain the "properties" property, the object is assumed to be unconstrained. That means, it may contain any properties of any type. +When an object type does not contain the "properties" property, the object is assumed to be unconstrained and therefore capable of containing any properties of any type. #### Additional Properties From ca62ce1b8be9928e0a06d0c8df8e0fbf13257645 Mon Sep 17 00:00:00 2001 From: Christian Vogel Date: Mon, 18 Apr 2016 11:44:44 +0100 Subject: [PATCH 109/241] further wordsmithing based on feedback --- versions/raml-10/raml-10.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/versions/raml-10/raml-10.md b/versions/raml-10/raml-10.md index 843545e9..a71067b7 100644 --- a/versions/raml-10/raml-10.md +++ b/versions/raml-10/raml-10.md @@ -1622,7 +1622,7 @@ baseUri: https://api.github.com The key of a resource property, i.e. its relative URI, MAY consist of multiple URI path fragments separated by slashes; e.g. /bom/items may indicate the collection of items in a bill of materials as a single resource. However, if the individual URI path fragments are themselves resources, the API definition SHOULD use nested resources to describe this structure; e.g. if /bom is itself a resource then /items should be a nested resource of /bom, vs using /bom/items as a non-nested resource. -Absolute URIs are not explicitly specified. They are computed by appending the relative URI of the top-level resource, and then successively appending the relative URI values for each nested resource until the target resource is reached. If and only if the baseUri is defined, the baseUri is appended to the first segment, which represents the top-level resource, of relative URIs. +Absolute URIs are not explicitly specified. They are computed by appending the relative URI of the top-level resource, and then successively appending the relative URI values for each nested resource until the target resource is reached. In this formation of the absolute URI, if a baseUri is defined, it is prepended before the relative URI of the top-level resource; any trailing slashes in the baseUri are removed before prepending. Taking the previous example, the absolute URI of the public gists resource is formed as follows. @@ -1671,7 +1671,7 @@ https://api.github.com/users/{userId}/keys https://api.github.com/users/{userId}/keys/{keyId} ``` -A RAML processor MUST NOT allow one of the computed absolute URIs to be identical to another one, without consideration to the possible values of any URI parameter. +A RAML processor MUST NOT allow one of the computed absolute URIs to be identical to another one; comparison of absolute URIs is done without consideration to the possible values of any URI parameter, i.e. any URI parameters are not expanded or evaluated but rather left as is. The following example would be forbidden. From f4d3de24763047acda696f84bd935fa70b2c9546 Mon Sep 17 00:00:00 2001 From: Christian Vogel Date: Mon, 18 Apr 2016 11:48:48 +0100 Subject: [PATCH 110/241] last workdsmithing based on feedback --- versions/raml-10/raml-10.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/versions/raml-10/raml-10.md b/versions/raml-10/raml-10.md index efa1cebc..b3aa9053 100644 --- a/versions/raml-10/raml-10.md +++ b/versions/raml-10/raml-10.md @@ -1189,7 +1189,7 @@ CatOrDog: # follows restrictions applied to the type 'Cat' ### Using XML and JSON Schema -RAML allows to not only define data using the type system, although it is recommended, but also provides mechanism to define them in XML and/or JSON schemas. RAML's type system allows seamless integration of JSON and XML schemas as type definitions. +RAML allows the use of XML and JSON schema to describe the body of an API request or response, by integrating them into its data type system. The following examples show how to include an external JSON schema into a root-level type definition and a body declaration. @@ -1241,9 +1241,9 @@ types: members: Person[] # invalid use of type expression '[]' and as a property type ``` -A RAML Processor MUST be able to interpret JSON Schema and XML Schema. +A RAML Processor MUST be able to interpret and apply JSON Schema and XML Schema. -XML schema MUST NOT be used where the media type does not allow XML-formatted data, and JSON schema MUST NOT be used where the media type does not allow JSON-formatted data. XML and JSON schemas are also FORBIDDEN in any declaration of query parameters, query string, and headers. +XML schema MUST NOT be used where the media type does not allow XML-formatted data, and JSON schema MUST NOT be used where the media type does not allow JSON-formatted data. XML and JSON schemas are also forbidden in any declaration of query parameters, query string, URI parameters, and headers. Please note that the properties "schemas" and "types" are completely synonymous, so are "schema" and "type" for compatibility with RAML 0.8, but "schemas" and "schema" are deprecated. API definitions should use "types" and "type", as "schemas" and "schema" may be removed in a future RAML version. From 4abc4f7071ddccdee6564f60bb64ccb69c12625f Mon Sep 17 00:00:00 2001 From: Christian Vogel Date: Mon, 18 Apr 2016 11:53:37 +0100 Subject: [PATCH 111/241] last wordsmithing before merge --- versions/raml-10/raml-10.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/versions/raml-10/raml-10.md b/versions/raml-10/raml-10.md index 9d2c45c3..6d7b7db1 100644 --- a/versions/raml-10/raml-10.md +++ b/versions/raml-10/raml-10.md @@ -434,7 +434,7 @@ declarations may have; certain type declarations may have other properties. |:----------|:----------| | default? | Provides a default value for a type. | schema? | Alias for the equivalent "type" property, for compatibility with RAML 0.8. Deprecated - API definitions should use the "type" property, as the "schema" alias for that property name may be removed in a future RAML version. The "type" property allows for XML and JSON schemas. -| type? | A base type which the current type extends, or more generally a type expression. The value of a `type` node MUST be either a) the name of a user-defined type or b) the name of a built-in RAML data type (object, array, or scalar type) or c) an inline type declaration. +| type? | A base type which the current type extends or just wraps. The value of a type node MUST be either a) the name of a user-defined type or b) the name of a built-in RAML data type (object, array, or one of the scalar types) or c) an inline type declaration. | example? | An example of an instance of this type. This can be used, e.g., by documentation generators to generate sample values for an object of this type. The `example` property MUST not be available when the `examples` property is already defined. | examples? | An object containing named examples of instances of this type. This can be used, e.g., by documentation generators to generate sample values for an object of this type. The `examples` property MUST not be available when the `example` property is already defined. See section [Examples](#defining-examples-in-raml) for more information. | displayName? | An alternate, human-friendly name for the type From 61a36f1616f16682aa35e0bde86d3a6c0b3d7d61 Mon Sep 17 00:00:00 2001 From: Christian Vogel Date: Mon, 18 Apr 2016 12:00:48 +0100 Subject: [PATCH 112/241] last wordsmithing before merging --- versions/raml-10/raml-10.md | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/versions/raml-10/raml-10.md b/versions/raml-10/raml-10.md index 91293f2f..8402164a 100644 --- a/versions/raml-10/raml-10.md +++ b/versions/raml-10/raml-10.md @@ -440,7 +440,7 @@ declarations may have; certain type declarations may have other properties. | displayName? | An alternate, human-friendly name for the type | description? | A longer, human-friendly description of the type | (<annotationName>)? | Annotations to be applied to this type. Annotations are any property whose key begins with "(" and ends with ")" and whose name (the part between the beginning and ending parentheses) is a declared annotation name. See section on [Annotations](#annotations) for more information. -| facets? | A map of user defined restrictions that are being inherited by a specific sub type. See section [User defined Facets](#user-defined-facets) for more information. +| facets? | A map of additional, user-defined restrictions that will be inherited and applied by any extending subtype. See section [User defined Facets](#user-defined-facets) for more information. | xml? | The ability to configure serialization of an instance of this type into XML. See section [XML Serialization of Type Instances](#xml-serialization-of-type-instances) for more information. The `schema` and `type` properties are mutually exclusive and synonymous: processors MUST NOT allow both to be specified (explicitly or implicitly) inside the same type declaration. Therefore, the following examples are both invalid. @@ -800,11 +800,11 @@ types: ### Scalar Types -RAML defines a set of built-in scalar types and each of them has a predefined set of restrictions. All these types, except the file type, may have an additional `enum` property. +RAML defines a set of built-in scalar types and each of them has a predefined set of restrictions. All these types, except the file type, may have an additional `enum` facet. -|Property Name | Description | +| Name | Description | |:--------|:------------| -| enum? | Enumeration of possible values for this built-in scalar type. The value is an array containing string representations of possible values, or a single string if there is only one possible value. +| enum? | Enumeration of possible values for this built-in scalar type. The value is an array containing representations of possible values, or a single value if there is only one possible value. Example usage of enums: From 8a8c021e46863c49963314ff6cc7cd56503994f7 Mon Sep 17 00:00:00 2001 From: Christian Vogel Date: Mon, 18 Apr 2016 12:40:15 +0100 Subject: [PATCH 113/241] added a more complex example for type instance validation against union types --- versions/raml-10/raml-10.md | 20 ++++++++++++++++++++ 1 file changed, 20 insertions(+) diff --git a/versions/raml-10/raml-10.md b/versions/raml-10/raml-10.md index 56d7a482..baf1e867 100644 --- a/versions/raml-10/raml-10.md +++ b/versions/raml-10/raml-10.md @@ -1190,6 +1190,26 @@ CatOrDog: # follows restrictions applied to the type 'Cat' color: "brown" ``` +Imagine a more complex example where a union type is used in a multiple inheritance type expression. + +```yaml +types: + HomeAnimal: [ HasHome , Dog | Cat ] +``` + +In this case type `HomeAnimal` has two base types `HasHome` and anonymous union type defined by a type expression - `Dog | Cat` + +So testing if the `HomeAnimal` type is a valid involves taking each of its base types, and checking that a type which is derived type of this type and each of union type option types is a valid type. In this particular case you need to test that types `[HasHome, Dog]` and `[HasHome, Cat]` are valid types. + +If you are extending from two union types you should do the same for every possible combination for example in this case: + +```yaml +types: + HomeAnimal: [ HasHome | IsOnFarm , Dog | Cat | Parrot ] +``` + +In summary, you need to test 6 possible combinations: `[HasHome, Dog ]`, `[HasHome, Cat ]`, `[HasHome, Parrot]`, `[IsOnFarm, Dog ]`, `[IsOnFarm, Cat ]`, and `[IsOnFarm, Parrot]`. + ### Using XML and JSON Schema RAML allows the use of XML and JSON schema to describe the body of an API request or response, by integrating them into its data type system. From 4a2164f8e9b3d001d7d2ccff16cc72bcdba8d7e4 Mon Sep 17 00:00:00 2001 From: Christian Vogel Date: Mon, 18 Apr 2016 12:52:48 +0100 Subject: [PATCH 114/241] moved the cyclic dependencies part from restrictions to introduction --- versions/raml-10/raml-10.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/versions/raml-10/raml-10.md b/versions/raml-10/raml-10.md index baf1e867..19a9a812 100644 --- a/versions/raml-10/raml-10.md +++ b/versions/raml-10/raml-10.md @@ -313,7 +313,7 @@ securitySchemes: ### Introduction -RAML 1.0 introduces the notion of **data types**, which provide a concise and powerful way of describing the data in an API. Data types add rules for validating data against a type declaration. Valid data adheres to all rules for the type. Data types can describe a base or resource URI parameter, a query parameter, a request or response header, or a request or response body. Data types are built-in or custom. A built-in type can be used anywhere the API expects data. Custom types can be defined by extending the built-in types. A type can be extended inline. Custom types can be named and then used like a built-in type. +RAML 1.0 introduces the notion of **data types**, which provide a concise and powerful way of describing the data in an API. Data types add rules for validating data against a type declaration. Valid data adheres to all rules for the type. Data types can describe a base or resource URI parameter, a query parameter, a request or response header, or a request or response body. Data types are built-in or custom. A built-in type can be used anywhere the API expects data. Custom types can be defined by extending the built-in types as well as named and used like built-in type. Extending types MUST NOT create any cyclic dependencies. A type can be extended inline. The following RAML example defines a User type that includes type declarations for the firstname, lastname, and age properties. The example declares the properties to be of built-in types string and number. Later, the User type serves to describe the type (schema) for a payload. From e74a2dbf2b3aa4a39ec6c9ea3b4a874f8149e313 Mon Sep 17 00:00:00 2001 From: Christian Vogel Date: Mon, 18 Apr 2016 12:59:31 +0100 Subject: [PATCH 115/241] removed inheritance restrictions chapter --- versions/raml-10/raml-10.md | 14 +------------- 1 file changed, 1 insertion(+), 13 deletions(-) diff --git a/versions/raml-10/raml-10.md b/versions/raml-10/raml-10.md index 19a9a812..28c62c97 100644 --- a/versions/raml-10/raml-10.md +++ b/versions/raml-10/raml-10.md @@ -1392,7 +1392,7 @@ types: type: [ A, B ] ``` -Note: Multiple inheritance is only allowed if all Type Expressions are simple object Types. See [Inheritance Restrictions](#inheritance-restrictions). +Note: Multiple inheritance is only allowed if all Type Expressions are simple object Types. If multiple parent types define a property with the same name: @@ -1426,18 +1426,6 @@ types: uniqueItems: true ``` -#### Inheritance Restrictions - -* You cannot inherit from types of different kind at the same moment ( kinds are: union types, array types, object types, scalar types ) -* You cannot inherit from types extending union types ( ex: you cannot extend from `Pet` if `Pet = Dog | Cat` ) -* You cannot inherit from multiple primitive types ( Multiple inheritance is only allowed for object types ) -* You cannot inherit from a type that extends Array type ( this will result in simple type aliasing/wrapping ) -* Facets are always inherited -* You can fix a previously defined facet to a value if the facet is defined on a superclass -* Properties are only allowed on object types -* You cannot create cyclic dependencies when inheriting -* You cannot inherit from "external" types - ### Shortcuts and Syntactic Sugar RAML Types are meant to be easy to read and write. To make the syntax more concise and in line with traditional object oriented programming languages, as well as familiar for developers who have used JSON schema before, the following shortcuts have been defined: From 1f2e9055c3c611a9d556bfb9ba9318ac432566ad Mon Sep 17 00:00:00 2001 From: Christian Vogel Date: Mon, 18 Apr 2016 13:05:28 +0100 Subject: [PATCH 116/241] removed shortcuts and semantic sugar chapter --- versions/raml-10/raml-10.md | 34 +--------------------------------- 1 file changed, 1 insertion(+), 33 deletions(-) diff --git a/versions/raml-10/raml-10.md b/versions/raml-10/raml-10.md index 28c62c97..124b7df2 100644 --- a/versions/raml-10/raml-10.md +++ b/versions/raml-10/raml-10.md @@ -512,7 +512,7 @@ types: type: number ``` -In order to achieve a more "object oriented" experience, a series of shortcuts are available (see [Shortcuts and Syntactic Sugar](#shortcuts-and-syntactic-sugar)). The example below shows a common idiom: +In order to achieve a more "object oriented" experience, a series of shortcuts are available. The example below shows a common idiom: ```yaml types: @@ -1426,38 +1426,6 @@ types: uniqueItems: true ``` -### Shortcuts and Syntactic Sugar - -RAML Types are meant to be easy to read and write. To make the syntax more concise and in line with traditional object oriented programming languages, as well as familiar for developers who have used JSON schema before, the following shortcuts have been defined: - - - - - - - - - - - - - - - - - - - - - - - - - - - -
      ExampleExpanded Equivalent
      Inline type expression gets expanded to a proper type declaration
      Email: string
      Email: 
        type: string
      `string` is default type when nothing else defined 
      Email:
      Email:
        type: string
      `object` is default type when `properties` is defined
      Person:
        properties:
      Person:
        type: object
        properties:
      Shorthand for Optional Property Syntax (?)
      Person:
        properties:
          nick?: string
      Person:
        type: object
        properties:
          nick:
            type: string
            required: false
      - ### Inline Type Declarations You can declare inline/anonymous types everywhere a type can be referenced other than in a Type Expression. From 6142f22832045295a7834be1a3052791c800d091 Mon Sep 17 00:00:00 2001 From: Christian Vogel Date: Mon, 18 Apr 2016 13:29:08 +0100 Subject: [PATCH 117/241] removed all occurences and links to the 'Inheritance and Specialization' chapter --- versions/raml-10/raml-10.md | 198 +----------------------------------- 1 file changed, 4 insertions(+), 194 deletions(-) diff --git a/versions/raml-10/raml-10.md b/versions/raml-10/raml-10.md index 124b7df2..c1cbeb38 100644 --- a/versions/raml-10/raml-10.md +++ b/versions/raml-10/raml-10.md @@ -381,16 +381,6 @@ types: type: Org ``` -These examples of type declarations contain the following advanced features: - -- Optional properties -- [Scalar Type Specialization](#scalar-type-specialization) -- [Inheritance](#inheritance) -- [Arrays](#array-types) -- [Enumerations](#enums) -- [Union Types](#union-types) -- [Maps](#map-types) - ### Overview The RAML type system borrows from object oriented programming languages such as Java, as well as from XSD and JSON Schemas. @@ -626,9 +616,9 @@ If a pattern property regular expression also matches an explicitly declared pro Moreover, if `additionalProperties` is `false` (explicitly or by inheritance) in a given type definition, then pattern properties are not allowed to be set explicitly in that definition. If it is `true` (or omitted) in a given type definition, then pattern properties are allowed and further restrict the allowed additional properties in that type. -#### Inheritance +#### Object Type Specialization -You can declare object types that inherit from other object types: +You can declare object types that inherit from other object types a sub-type inherits all the properties of its parent type. In the example below, the type `Employee` inherits all properties of its parent type `Person`. ```yaml #%RAML 1.0 @@ -646,27 +636,7 @@ types: type: string ``` -You can inherit from more than one type: - -```yaml -#%RAML 1.0 -title: My API With Types -types: - Person: - type: object - properties: - name: string - EmailOwner: - type: object - properties: - email: string - Employee: - type: [ Person, EmailOwner ] - properties: - id: string -``` - -For more details see [Object Type Inheritance](#object-type-inheritance) +Any sub-types can override properties defined in its parent types with the following two restrictions: 1) if a property is required in the parent type, it cannot be made optional in the sub-type, and 2) the type of an already defined property can only be changed to a narrower type (a type that specializes the parent type). #### Using Discriminator @@ -1109,33 +1079,6 @@ Type expressions are composed of names of built-in or custom types and certain s | (type expression)[] | Array operator: a unary postfix operator placed after another type expression (enclosed in parentheses, as needed) and indicating that the resulting type is an array of instances of that type expression. | `string[]:` an array of strings

      `Person[][]:` an array of arrays of Person instances | (type expression 1) | (type expression 2) | Union operator: an infix operator indicating that the resulting type may be either of type expression 1 or of type expression 2. Multiple union operators may be combined between pairs of type expressions. | `string | number:` either a string or a number

      `X | Y | Z`: either an X or a Y or a Z

      `(Manager | Admin)[]:` an array whose members consist of Manager or Admin instances

      `Manager[] | Admin[]:` an array of Manager instances or an array of Admin instances. -There are additional constraints on type expressions when used to define inheritance. They are described at [Rules of Inheritance](#inheritance-and-specialization). For example, the following is not valid (you cannot add properties to a union type). - - -```yaml -#%RAML 1.0 -title: My API With Types -types: - Phone: - type: object - properties: - manufacturer: - type: string - numberOfSIMCards: - type: number - Notebook: - type: object - properties: - manufacturer: - type: string - numberOfUSBPorts: - type: number - Device: - type: Phone | Notebook - properties: - weight: number -``` - ### Union Types Union Types are declared using pipes (|) in your type expressions. Union Types are useful to model common scenarios in JSON based applications, for example an array containing objects which can be instances of more than one type. @@ -1270,113 +1213,7 @@ XML schema MUST NOT be used where the media type does not allow XML-formatted da Please note that the properties "schemas" and "types" are completely synonymous, so are "schema" and "type" for compatibility with RAML 0.8, but "schemas" and "schema" are deprecated. API definitions should use "types" and "type", as "schemas" and "schema" may be removed in a future RAML version. -### Inheritance and Specialization - -When declaring a RAML Type you are always inheriting from, or specializing, an existing type. The general syntax for inheritance is: - -```yaml -MyType: - type: ParentTypeExpression -``` - -Depending on the value of `ParentTypeExpression`, though, the meaning of inheritance will change. It is important to understand the differences: - -```yaml -#%RAML 1.0 -title: My API With Types -types: - Person: - type: object - properties: - name: string - MyType: - type: Person - properties: - x: string -``` - -```yaml -#%RAML 1.0 -title: My API With Types -types: - Person: - type: object - properties: - name: string - Auditable: - type: object - properties: - personalId: number - Employee: - type: [Person, Auditable] - properties: - positionName: string -``` - -```yaml -#%RAML 1.0 -title: My API With Types -types: - MyType: - type: number - minimum: 0 -``` - -```yaml -#%RAML 1.0 -title: My API With Types -types: - Person: - type: object - properties: - name: string - MyType: - type: Person[] - uniqueItems: true -``` - -```yaml -#%RAML 1.0 -title: My API With Types -types: - Phone: - type: object - properties: - someNumberProperty: - type: number - Notebook: - type: object - properties: - someStringProperty: - type: string - MyType: - type: Notebook | Phone -``` - -Each Inheritance type is explained in detail in the following sections: - -#### Object Type Specialization - -Object inheritance works like normal Object Oriented inheritance. A subtype inherits all the properties of its parent type. - -```yaml -#%RAML 1.0 -title: My API With Types -types: - B: - type: object - A: - type: B -``` - -##### Property Overrides - -Subtypes can override properties defined in parent types. There are two restrictions: - -* If a property is required in the parent, it cannot be made optional in the subtype -* The type of an already defined property can only be changed to a narrower type ( a type that specializes the parent type ) - -##### Multiple Inheritance +### Multiple Inheritance RAML Types support multiple inheritance for object types. This is achieved by passing a sequence of types: @@ -1399,33 +1236,6 @@ If multiple parent types define a property with the same name: * The property will be required if at least one of the declarations are required * The type of the property will be the narrowest type - -#### Scalar Type Specialization - -If the type expression is a simple scalar type, specialization is achieved by setting values for previously defined facets. - -#### Array Type Specialization - -If the outer type of the type expression is an array you can set a value for the available array type facets: - -| Property | Description | -|:----------|:----------| -| uniqueItems? | Boolean value that indicates if items in the array MUST be unique. -| items? | Indicates what type all items in the array inherit from. Can be a reference to an existing type or an inline [type declaration](#type-declaration) -| minItems? | Minimum amount of items in array. Value MUST be equal or greater than 0. Defaults to 0. -| maxItems? | Maximum amount of items in array. Value MUST be equal or greater than 0. Defaults to 2147483647. - -The example below defines an array of numbers and sets its "uniqueItems" facet to true. - -```yaml -#%RAML 1.0 -title: My API With Types -types: - NumberSet: - type: number[] - uniqueItems: true -``` - ### Inline Type Declarations You can declare inline/anonymous types everywhere a type can be referenced other than in a Type Expression. From 5174b43a688abbe2155400d38905785c0d3a3162 Mon Sep 17 00:00:00 2001 From: Christian Vogel Date: Mon, 18 Apr 2016 14:29:48 +0100 Subject: [PATCH 118/241] wordsmithing and content consistency inside the type system chapter --- versions/raml-10/raml-10.md | 61 ++++++++++++++++++------------------- 1 file changed, 30 insertions(+), 31 deletions(-) diff --git a/versions/raml-10/raml-10.md b/versions/raml-10/raml-10.md index edd59a7b..69bebb29 100644 --- a/versions/raml-10/raml-10.md +++ b/versions/raml-10/raml-10.md @@ -406,7 +406,7 @@ The following diagram shows the type families and examples of these custom types ### Type Declarations -Types may be declared inline, wherever the API expects data, or in an OPTIONAL **types** property at the root of the API or in an included library. The value is a map where each key represents the name of the type and its value is a type declaration. +Types can be declared inline where the API expects data, in an OPTIONAL **types** property at the root of the API, or in an included library. To declare a type, you use a map where the key represents the name of the type and its value is a type declaration. ```yaml types: @@ -414,22 +414,22 @@ types: # value is a type declaration ``` -Types declarations are used to extend built-in types or other custom types, as well as to add more information to types such as specific examples or annotations. Here are the properties that all type declarations may have; certain type declarations may have other properties. +A type declaration can extend a built-in type or other custom type, or add more information to types, such as specific examples or annotations. Here are the facets that all type declarations can have; certain type declarations might have other facets: -| Property | Description | +| Facet | Description | |:----------|:----------| -| default? | Provides a default value for a type. -| schema? | Alias for the equivalent "type" property, for compatibility with RAML 0.8. Deprecated - API definitions should use the "type" property, as the "schema" alias for that property name may be removed in a future RAML version. The "type" property allows for XML and JSON schemas. +| default? | A default value for a type. +| schema? | An alias for the equivalent "type" property for compatibility with RAML 0.8. Deprecated - API definitions should use the "type" property because the "schema" alias for that property name might be removed in a future RAML version. The "type" property supports XML and JSON schemas. | type? | A base type which the current type extends or just wraps. The value of a type node MUST be either a) the name of a user-defined type or b) the name of a built-in RAML data type (object, array, or one of the scalar types) or c) an inline type declaration. -| example? | An example of an instance of this type. This can be used, e.g., by documentation generators to generate sample values for an object of this type. The `example` property MUST not be available when the `examples` property is already defined. -| examples? | An object containing named examples of instances of this type. This can be used, e.g., by documentation generators to generate sample values for an object of this type. The `examples` property MUST not be available when the `example` property is already defined. See section [Examples](#defining-examples-in-raml) for more information. +| example? | An example of an instance of this type that can be used, for example, by documentation generators to generate sample values for an object of this type. The "example" property MUST not be available when the "examples" property is already defined. See section [Examples](#defining-examples-in-raml) for more information. +| examples? | An object containing named examples of instances of this type. This can be used, for example, by documentation generators to generate sample values for an object of this type. The "examples" property MUST not be available when the "example" property is already defined. See section [Examples](#defining-examples-in-raml) for more information. | displayName? | An alternate, human-friendly name for the type -| description? | A longer, human-friendly description of the type -| (<annotationName>)? | Annotations to be applied to this type. Annotations are any property whose key begins with "(" and ends with ")" and whose name (the part between the beginning and ending parentheses) is a declared annotation name. See section on [Annotations](#annotations) for more information. +| description? | A substantial, human-friendly description of the type +| (<annotationName>)? | [Annotations](#annotations) to be applied to this type. An annotation is a property having a key that begins with "(" and ends with ")". The text enclosed in parentheses is the annotation name. | facets? | A map of additional, user-defined restrictions that will be inherited and applied by any extending subtype. See section [User defined Facets](#user-defined-facets) for more information. -| xml? | The ability to configure serialization of an instance of this type into XML. See section [XML Serialization of Type Instances](#xml-serialization-of-type-instances) for more information. +| xml? | The capability to configure [XML serialization of this type instance](#xml-serialization-of-type-instances). -The `schema` and `type` properties are mutually exclusive and synonymous: processors MUST NOT allow both to be specified (explicitly or implicitly) inside the same type declaration. Therefore, the following examples are both invalid. +The "schema" and "type" facets are mutually exclusive and synonymous: processors MUST NOT allow both to be specified, explicitly or implicitly, inside the same type declaration. Therefore, the following examples are invalid: ```yaml types: @@ -449,19 +449,19 @@ types: type: # invalid as mutually exclusive with `schema` ``` -It is recommended to use the `type` property instead of `schema`, as the `schema` alias is deprecated and may be removed in a future RAML version. The `type` property also allows for XML and JSON schemas. +We recommended using the "type" facet instead of "schema" because the schema alias is deprecated and might be removed in a future RAML version. Also, the "type" facet supports XML and JSON schemas. ### Object Types -All types that have the built-in object type at the root of their inheritance tree can use the following properties in their type declarations: +All types that have the built-in object type at the root of their inheritance tree can use the following facets in their type declarations: -| Property | Description | +| Facet | Description | |:----------|:----------| | properties? | The [properties](#property-declarations) that instances of this type can or must have. | minProperties? | The minimum number of properties allowed for instances of this type. | maxProperties? | The maximum number of properties allowed for instances of this type. | additionalProperties? | A Boolean that indicates if an object instance has [additional properties](#additional-properties).

      **Default:** `true` -| discriminator? | Determines the concrete type of an individual object at runtime when, for example, payloads contain ambiguous types due to unions or inheritance. The value must match the name of one of the declared `properties` of a type. Unsupported practices are inline type declarations and [using `discriminator`](#using-discriminator) with non-scalar properties. +| discriminator? | Determines the concrete type of an individual object at runtime when, for example, payloads contain ambiguous types due to unions or inheritance. The value must match the name of one of the declared `properties` of a type. Unsupported practices are inline type declarations and [using `discriminator`](#using-discriminator) with non-scalar properties. | discriminatorValue? | Identifies the declaring type. Requires including a `discriminator` property in the type declaration. A valid value is an actual value that might identify the type of an individual object and is unique in the hierarchy of the type. Inline type declarations are not supported.

      **Default:** The name of the type An object type is created by explicit inheritance from the built-in type object: @@ -480,11 +480,11 @@ types: #### Property Declarations -Properties of object types are defined using the OPTIONAL **properties** property. The RAML Specification calls the value of the properties property a "properties declaration". The properties declaration is a map of keys and values. The keys are valid property names for declaring a type instance. The values are either a name of a type or an inline type declaration. +Properties of object types are defined using the OPTIONAL **properties** facet. The RAML Specification calls the value of the "properties" facet a "properties declaration". The properties declaration is a map of keys and values. The keys are valid property names for declaring a type instance. The values are either a name of a type or an inline type declaration. The properties declaration can specify whether a property is required or optional. -| Property | Description | +| Facet | Description | |:----------|:----------| | required? | Specifies that the property is required or not.

      **Default:** `true`. @@ -550,11 +550,11 @@ types: Note: -When an object type does not contain the "properties" property, the object is assumed to be unconstrained and therefore capable of containing any properties of any type. +When an object type does not contain the "properties" facet, the object is assumed to be unconstrained and therefore capable of containing any properties of any type. #### Additional Properties -By default any instance of an object can have additional properties beyond those specified in its data type `properties` node. Let's assume the following is an instance of the data type `Person` that is described in the previous section. +By default any instance of an object can have additional properties beyond those specified in its data type `properties` facet. Let's assume the following is an instance of the data type `Person` that is described in the previous section. ```yaml Person: @@ -644,7 +644,7 @@ When payloads contain ambiguous types (achieved via unions or inheritance) it is A RAML processor may provide an implementation that automatically select a concrete type from a set of possible types, but one of the simplest options is to actually store some unique value associated with the type inside the object. -The `discriminator` property allows you to set the name of an object property which will be used to discriminate the concrete type, and `discriminatorValue` stores the actual value that may identify the type of an individual object. By default, the value of `discriminatorValue` is the name of the type. +The `discriminator` facet allows you to set the name of an object property which will be used to discriminate the concrete type, and `discriminatorValue` stores the actual value that may identify the type of an individual object. By default, the value of `discriminatorValue` is the name of the type. Here's an example that illustrates how to use `discriminator`: @@ -740,9 +740,9 @@ PersonOrDog: ### Array Types -Array Types are declared by either using the array qualifier `[]` at the end of a [type expression](#type-expressions) or `array` as the value of a `type` node. If you are defining a top-level array type (like the example below), you can pass the following additional properties to further restrict its behavior. +Array Types are declared by either using the array qualifier `[]` at the end of a [type expression](#type-expressions) or `array` as the value of a `type` node. If you are defining a top-level array type (like the example below), you can pass the following additional facets to further restrict its behavior. -| Property | Description | +| Facet | Description | |:----------|:----------| | uniqueItems? | Boolean value that indicates if items in the array MUST be unique. | items? | Indicates what type all items in the array inherit from. Can be a reference to an existing type or an inline [type declaration](#type-declaration) @@ -784,7 +784,7 @@ Using `Email[]` is equivalent to use `type: array` and specifically define the t RAML defines a set of built-in scalar types and each of them has a predefined set of restrictions. All these types, except the file type, may have an additional `enum` facet. -| Name | Description | +| Facet | Description | |:--------|:------------| | enum? | Enumeration of possible values for this built-in scalar type. The value is an array containing representations of possible values, or a single value if there is only one possible value. @@ -807,7 +807,7 @@ types: A JSON string with the following additional facets: -|Property Name | Description | +| Facet | Description | |:--------|:------------| | pattern? | Regular expression that this string should pass. | minLength? | Minimum length of the string. Value MUST be equal or greater than 0.

      **Default:** `0` @@ -827,7 +827,7 @@ types: Any JSON number including [integer](#integer) with the following additional facets: -|Property Name | Description | +| Facet | Description | |:--------|:------------| |minimum? | (applicable only for parameters of type number or integer) The minimum attribute specifies the parameter's minimum value. |maximum? | (applicable only for parameters of type number or integer) The maximum attribute specifies the parameter's maximum value. @@ -908,7 +908,7 @@ types: The ​**file**​ type can be used to constrain the content to send through forms. When it is used in the context of web forms it SHOULD be represented as a valid file upload, and in JSON representation, it SHOULD be represented as a base64 encoded string with a file content. -|Property Name | Description | +| Facet | Description | |:--------|:------------| | fileTypes? | List of valid content-types for the file. The file type `*/*` should be a valid value. | minLength? | Specifies the parameter value's minimum number of bytes. Value MUST be equal or greater than 0.

      **Default:** `0` @@ -948,7 +948,7 @@ Because user-defined facets are by definition not built into this RAML specifica A RAML processor must be able to determine the default type of a type declaration by using the following rules: -* If, and only if, a type declaration contains a `properties` node; the default type is `object`. For example (based on this rule): +* If, and only if, a type declaration contains a `properties` facet; the default type is `object`. For example (based on this rule): ```yaml types: @@ -966,7 +966,7 @@ types: properties: ``` -* If, and only if, a type declaration contains neither a `properties` node nor a `type` or `schema` node, then the default type is `string`. For example (based on this rule): +* If, and only if, a type declaration contains neither a `properties` facet nor a `type` or `schema` facet, then the default type is `string`. For example (based on this rule): ```yaml types: @@ -1002,8 +1002,7 @@ types: ### Type Expressions -So far we have only used simple type identifiers to refer to other Types (ex: string, object, Person). Type Expressions provide a powerful way of referring to, and even defining, types. Type Expressions can be used wherever a type is expected. -The simplest Type Expression is just the name of a type. But Type expressions also allow you to express Type Unions, Arrays, and maps amongst other things. +So far we have only used simple type identifiers to refer to other Types (ex: string, object, Person). Type Expressions provide a powerful way of referring to, and even defining, types. Type Expressions can be used wherever a type is expected. The simplest Type Expression is just the name of a type. But Type expressions also allow you to express Type Unions, Arrays, and maps amongst other things. |Expression | Description | |:--------|:------------| @@ -1293,7 +1292,7 @@ content: You have been added to group 274 ##### The value is a map that contains the following additional facets -|Property | Description | +| Facet | Description | |:--------|:------------| | displayName? | An alternate, human-friendly name for the example. If the example is part of an examples node, the default value is the unique identifier that is defined for this example. | description? | A longer, human-friendly description of the example. From 337083631d1d45d74ac5788032cccb063e369907 Mon Sep 17 00:00:00 2001 From: Christian Vogel Date: Mon, 18 Apr 2016 15:46:46 +0100 Subject: [PATCH 119/241] added another example to the multiple inheritance section --- versions/raml-10/raml-10.md | 45 ++++++++++++++++++++++++++++--------- 1 file changed, 34 insertions(+), 11 deletions(-) diff --git a/versions/raml-10/raml-10.md b/versions/raml-10/raml-10.md index 69bebb29..2717941c 100644 --- a/versions/raml-10/raml-10.md +++ b/versions/raml-10/raml-10.md @@ -1214,26 +1214,49 @@ Please note that the properties "schemas" and "types" are completely synonymous, ### Multiple Inheritance -RAML Types support multiple inheritance for object types. This is achieved by passing a sequence of types: +RAML Types support multiple inheritance. This is achieved by passing a sequence of types: ```yaml -#%RAML 1.0 -title: My API With Types types: - A: + Person: type: object - B: + properties: + name: string + Employee: type: object - C: - type: [ A, B ] + properties: + employeeNr: integer + Teacher: + type: [ Person, Employee ] ``` -Note: Multiple inheritance is only allowed if all Type Expressions are simple object Types. +The type `Teacher` inherits all properties from `Person` and `Employee`. -If multiple parent types define a property with the same name: +Note: Multiple inheritance is only allowed if the resulting type is a valid type declaration. For example, the type `Number3` is fully valid: -* The property will be required if at least one of the declarations are required -* The type of the property will be the narrowest type +```yaml +types: + Number1: + type: number + minimum: 4 + Number2: + type: number + maximum: 10 + Number3: [ Number1, Number2] +``` + +Where as using the same example and only change the maximum value of type `Number2` from 10 to 2 would result into an invalid type `Number3`. + +```yaml +types: + Number1: + type: number + minimum: 4 + Number2: + type: number + maximum: 2 + Number3: [ Number1, Number2] # invalid, maximum value cannot be lesser than minimum value +``` ### Inline Type Declarations From b605e6f659423a87efd30ddbde87af64adac634a Mon Sep 17 00:00:00 2001 From: Christian Vogel Date: Mon, 18 Apr 2016 15:55:06 +0100 Subject: [PATCH 120/241] fixed examples for traits and annotations --- versions/raml-10/raml-10.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/versions/raml-10/raml-10.md b/versions/raml-10/raml-10.md index 69bebb29..a8da0f4b 100644 --- a/versions/raml-10/raml-10.md +++ b/versions/raml-10/raml-10.md @@ -2254,7 +2254,7 @@ All the collections or sequences which fall under effect of applying traits and title: Example API version: v1 traits: - parameters: + withQueryParameters: queryParameters: platform: enum: @@ -3209,7 +3209,7 @@ usage: Hints for monitoring the library books API extends: librarybooks.raml annotationTypes: monitor: - parameters: + properties: frequency: properties: interval: integer From 1ef1953003ff966a153f86fa6c3d99ba4cccdd29 Mon Sep 17 00:00:00 2001 From: Christian Vogel Date: Mon, 18 Apr 2016 19:04:52 +0100 Subject: [PATCH 121/241] wordsmithing --- versions/raml-10/raml-10.md | 22 ++++++++++++---------- 1 file changed, 12 insertions(+), 10 deletions(-) diff --git a/versions/raml-10/raml-10.md b/versions/raml-10/raml-10.md index 2717941c..87978004 100644 --- a/versions/raml-10/raml-10.md +++ b/versions/raml-10/raml-10.md @@ -1230,22 +1230,22 @@ types: type: [ Person, Employee ] ``` -The type `Teacher` inherits all properties from `Person` and `Employee`. +In the example above, the type `Teacher` inherits all restrictions from `Person` and `Employee`. -Note: Multiple inheritance is only allowed if the resulting type is a valid type declaration. For example, the type `Number3` is fully valid: +Multiple inheritance is only allowed if the sub-type is still a valid type declaration after inheriting all restrictions from its parent types. For example, the type `Number3` is fully valid: ```yaml types: - Number1: - type: number - minimum: 4 - Number2: - type: number - maximum: 10 - Number3: [ Number1, Number2] + Number1: + type: number + minimum: 4 + Number2: + type: number + maximum: 10 + Number3: [ Number1, Number2] ``` -Where as using the same example and only change the maximum value of type `Number2` from 10 to 2 would result into an invalid type `Number3`. +Whereas using the same example and only change the maximum value of type `Number2` from 10 to 2 would result into an invalid type `Number3`. ```yaml types: @@ -1258,6 +1258,8 @@ types: Number3: [ Number1, Number2] # invalid, maximum value cannot be lesser than minimum value ``` +If a sub-type inherits properties with the same name from at least two of its parent types, the sub-type keeps all restrictions applied to those properties except if a parent type already declares a "pattern" facet and if there are two user-defined facets with the same value, which in both cases ends as an invalid type declaration. + ### Inline Type Declarations You can declare inline/anonymous types everywhere a type can be referenced other than in a Type Expression. From c09960b84cf3dd06abd5311f91043b7a2b55bcbc Mon Sep 17 00:00:00 2001 From: Kris Hahn Date: Mon, 18 Apr 2016 20:35:07 -0700 Subject: [PATCH 122/241] Update raml-10.md editorial suggestions --- versions/raml-10/raml-10.md | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/versions/raml-10/raml-10.md b/versions/raml-10/raml-10.md index 87978004..71ef4171 100644 --- a/versions/raml-10/raml-10.md +++ b/versions/raml-10/raml-10.md @@ -1232,7 +1232,7 @@ types: In the example above, the type `Teacher` inherits all restrictions from `Person` and `Employee`. -Multiple inheritance is only allowed if the sub-type is still a valid type declaration after inheriting all restrictions from its parent types. For example, the type `Number3` is fully valid: +Multiple inheritance is allowed only if the sub-type is still a valid type declaration after inheriting all restrictions from its parent types. For example, the type `Number3` is valid: ```yaml types: @@ -1245,7 +1245,7 @@ types: Number3: [ Number1, Number2] ``` -Whereas using the same example and only change the maximum value of type `Number2` from 10 to 2 would result into an invalid type `Number3`. +Whereas using the same example and only changing the maximum value of type `Number2` from 10 to 2 would result in an invalid type `Number3`. ```yaml types: @@ -1255,10 +1255,10 @@ types: Number2: type: number maximum: 2 - Number3: [ Number1, Number2] # invalid, maximum value cannot be lesser than minimum value + Number3: [ Number1, Number2] # invalid, maximum value cannot be less than minimum value ``` -If a sub-type inherits properties with the same name from at least two of its parent types, the sub-type keeps all restrictions applied to those properties except if a parent type already declares a "pattern" facet and if there are two user-defined facets with the same value, which in both cases ends as an invalid type declaration. +If a sub-type inherits properties having the same name from at least two of its parent types, the sub-type keeps all restrictions applied to those properties with two exceptions: a parent type already declares a "pattern" facet and two user-defined facets have same value. In these cases, an invalid type declaration occurs. ### Inline Type Declarations From 6233e1e86d220c3f222ddb11c1f7e4203d4b9f2a Mon Sep 17 00:00:00 2001 From: Kris Hahn Date: Mon, 18 Apr 2016 20:46:06 -0700 Subject: [PATCH 123/241] Update raml-10.md minor edit --- versions/raml-10/raml-10.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/versions/raml-10/raml-10.md b/versions/raml-10/raml-10.md index 71ef4171..e1097479 100644 --- a/versions/raml-10/raml-10.md +++ b/versions/raml-10/raml-10.md @@ -1258,7 +1258,7 @@ types: Number3: [ Number1, Number2] # invalid, maximum value cannot be less than minimum value ``` -If a sub-type inherits properties having the same name from at least two of its parent types, the sub-type keeps all restrictions applied to those properties with two exceptions: a parent type already declares a "pattern" facet and two user-defined facets have same value. In these cases, an invalid type declaration occurs. +If a sub-type inherits properties having the same name from at least two of its parent types, the sub-type keeps all restrictions applied to those properties with two exceptions: a parent type already declares a "pattern" facet and two user-defined facets have the same value. In these cases, an invalid type declaration occurs. ### Inline Type Declarations From abf93471bea5f12a1df9725b2f93288db0c18d57 Mon Sep 17 00:00:00 2001 From: krishahn Date: Mon, 18 Apr 2016 22:18:22 -0700 Subject: [PATCH 124/241] copyedits --- versions/raml-10/raml-10.md | 13 ++++++------- 1 file changed, 6 insertions(+), 7 deletions(-) diff --git a/versions/raml-10/raml-10.md b/versions/raml-10/raml-10.md index a8da0f4b..8c6e1d7e 100644 --- a/versions/raml-10/raml-10.md +++ b/versions/raml-10/raml-10.md @@ -3026,16 +3026,15 @@ schema: !include elements.xsd#Foo /id: !include myContent.raml#feature ``` -Dereferencing to a fragment of JSON schemas is performed according to default JSON Schema dereferencing rules (see chapter 7 in http://json-schema.org/latest/json-schema-core.html) +Dereferencing a fragment of a JSON schema is supported as described in the JSON Schema dereferencing rules in Chapter 7 of [_JSON Schema: core definitions and terminology_](http://json-schema.org/latest/json-schema-core.html) -Dereferencing to a fragment of XSD schema is described in *3.15.2.2 References to Schema Components*, [XML Schema Part 1: Structures Second Edition](http://www.w3.org/TR/xmlschema-1/). However there is a special shortcut: If you are referring to a named type within XSD schema you may simplify fragment definition to its name. +Dereferencing a fragment of an XSD is supported as described in section "3.15.2.2 References to Schema Components from Elsewhere" of [_XML Schema Part 1: Structures Second Edition_](http://www.w3.org/TR/xmlschema-1/). However, you can also refer to a named type in an XSD schema. -Meaning of references to inner elements: referencing to inner element of schema is equivalent to referencing to the schema with a top level element with structural restrictions same as restrictions on the referenced element of schema. At this version of RAML specification it is allowed to refer on elements of schemas in the following cases: +Referencing an inner element of a schema is equivalent to referencing a top level element. The structural restrictions on referencing an inner element are the same as those on referencing other elements. This version of RAML specification supports references to elements of schemas in the following cases: -* referencing to an element of JSON schema is valid in any context, but they do not define name of top level XML element when serializing to XML payload -* referencing to an element of XSD schema is valid in any context -* references to XSD complex types are valid to determine inner structure of payload but they do not define name of top level XML element when serializing to XML payload -* any other kinds of references does not have well defined meaning +* Referencing an element of a JSON schema in any context. The name of top level XML element of data that is serialized to an XML payload is not defined. +* Referencing an element of an XSD in any context. +* Referencing XSD complex types to determine the inner structure of payload. The name of top level XML element of data that is serialized to an XML payload is not defined. ### Libraries From 5ba450a47511512b46da5b363cd85f3aa8a8ee51 Mon Sep 17 00:00:00 2001 From: Kris Hahn Date: Mon, 18 Apr 2016 23:38:01 -0700 Subject: [PATCH 125/241] Update raml-10.md clarification --- versions/raml-10/raml-10.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/versions/raml-10/raml-10.md b/versions/raml-10/raml-10.md index e1097479..1b19be69 100644 --- a/versions/raml-10/raml-10.md +++ b/versions/raml-10/raml-10.md @@ -1258,7 +1258,7 @@ types: Number3: [ Number1, Number2] # invalid, maximum value cannot be less than minimum value ``` -If a sub-type inherits properties having the same name from at least two of its parent types, the sub-type keeps all restrictions applied to those properties with two exceptions: a parent type already declares a "pattern" facet and two user-defined facets have the same value. In these cases, an invalid type declaration occurs. +If a sub-type inherits properties having the same name from at least two of its parent types, the sub-type keeps all restrictions applied to those properties with two exceptions: 1) a "pattern" facet when a parent type already declares a "pattern" facet 2) a user-defined facet when another user-defined facet has the same value. In these cases, an invalid type declaration occurs. ### Inline Type Declarations From 5bed96b6c3f8b1d4ce63dfd25b9409b37894ffba Mon Sep 17 00:00:00 2001 From: Christian Vogel Date: Tue, 19 Apr 2016 11:46:50 +0100 Subject: [PATCH 126/241] fixed discriminator example to use integer instead of string --- versions/raml-10/raml-10.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/versions/raml-10/raml-10.md b/versions/raml-10/raml-10.md index a8da0f4b..31f8dcd8 100644 --- a/versions/raml-10/raml-10.md +++ b/versions/raml-10/raml-10.md @@ -661,11 +661,11 @@ types: Employee: # kind may equal to `Employee; default value for `discriminatorValue` type: Person properties: - employeeId: string + employeeId: integer User: # kind may equal to `User`; default value for `discriminatorValue` type: Person properties: - userId: string + userId: integer ``` ```yaml From 5816523f9efbe47ed8e4ce7ce649e3ab91b61071 Mon Sep 17 00:00:00 2001 From: Christian Vogel Date: Tue, 19 Apr 2016 11:53:18 +0100 Subject: [PATCH 127/241] make types and schemas mutual exclusive --- versions/raml-10/raml-10.md | 2 ++ 1 file changed, 2 insertions(+) diff --git a/versions/raml-10/raml-10.md b/versions/raml-10/raml-10.md index 31f8dcd8..68d050b6 100644 --- a/versions/raml-10/raml-10.md +++ b/versions/raml-10/raml-10.md @@ -155,6 +155,8 @@ The following table enumerates the possible properties at the root of a RAML doc | uses? | Imported external [libraries](#libraries) for use within the API. | /<relativeUri>? | The resources of the API, identified as relative URIs that begin with a slash (/). A [resource property](#resources-and-nested-resources) is one that begins with the slash and is either at the root of the API definition or a child of a resource property. For example, /users and /{groupId}. +The "schemas" and "types" nodes are mutually exclusive and synonymous: processors MUST NOT allow both to be specified, explicitly or implicitly, at the root-level of an API definition. We recommended using the "types" node instead of "schemas" because the schemas alias is deprecated and might be removed in a future RAML version. Also, the "types" node supports XML and JSON schemas. + ### User Documentation The OPTIONAL **documentation** property includes a variety of documents that serve as user guides and reference documentation for the API. Such documents can clarify how the API works or provide technical and business context. From 68f58356b1e40e1387bc3afeac9978df240918b3 Mon Sep 17 00:00:00 2001 From: krishahn Date: Tue, 19 Apr 2016 11:40:42 -0700 Subject: [PATCH 128/241] copyedit Additional Properties section --- versions/raml-10/raml-10.md | 16 ++++++++-------- 1 file changed, 8 insertions(+), 8 deletions(-) diff --git a/versions/raml-10/raml-10.md b/versions/raml-10/raml-10.md index 31f8dcd8..484a0857 100644 --- a/versions/raml-10/raml-10.md +++ b/versions/raml-10/raml-10.md @@ -554,7 +554,7 @@ When an object type does not contain the "properties" facet, the object is assum #### Additional Properties -By default any instance of an object can have additional properties beyond those specified in its data type `properties` facet. Let's assume the following is an instance of the data type `Person` that is described in the previous section. +By default, any instance of an object can have additional properties beyond those specified in its data type `properties` facet. Assume the following code is an instance of the data type `Person` that is described in the previous section. ```yaml Person: @@ -563,9 +563,9 @@ Person: note: "US" # valid additional property `note` ``` -The property `note` has been not explicitly declared in the `Person` data type, but is valid based on the fact that all additional properties are by default valid. +The property `note` is not explicitly declared in the `Person` data type, but is valid because all additional properties are valid by default. -To restrict that, one can either use the `additionalProperties` facet to not allow any additional properties by setting the value to `false`, or by specifying regular expression patterns that matches sets of keys and restricts their values: these are called "pattern properties". The patterns are delineated by pairs of opening and closing `/` characters, as follows: +To restrict the addition of properties, you can set the value of the `additionalProperties` facet to `false`, or you can specify regular expression patterns that match sets of keys and restrict their values. The latter are called "pattern properties". The patterns are delineated by pairs of opening and closing `/` characters, as follows: ```yaml #%RAML 1.0 @@ -580,18 +580,18 @@ types: required: false type: number /^note\d+$/: # restrict any properties whose keys start with "note" - # followed by one or more digits to be a string + # followed by a string of one or more digits type: string ``` -This restricts any additional properties whose keys start with "note" followed by one or more digits to be a string. Where as the example of an object instance with an additional `note` property with value "US" is valid, the following is not: +This pattern property restricts any additional properties whose keys start with "note" followed by a string of one or more digits. Consequently, the example of an object instance that declares an additional `note` property with the value "US" is valid, but the same property is invalid with a non-string value: ```yaml Person: name: "John" age: 35 note: 123 # not valid as it is not a string - address: "US" # valid is it does not match the pattern + address: "US" # valid as it does not match the pattern ``` To force all additional properties to be strings, regardless of their keys, use: @@ -612,9 +612,9 @@ types: type: string ``` -If a pattern property regular expression also matches an explicitly declared property, the explicitly declared property's definition prevails. If two or more pattern property regular expressions match a property name in an instance of the data type, the first one prevails. +If a pattern property regular expression also matches an explicitly declared property, the explicitly declared property definition prevails. If two or more pattern property regular expressions match a property name in an instance of the data type, the first one prevails. -Moreover, if `additionalProperties` is `false` (explicitly or by inheritance) in a given type definition, then pattern properties are not allowed to be set explicitly in that definition. If it is `true` (or omitted) in a given type definition, then pattern properties are allowed and further restrict the allowed additional properties in that type. +Moreover, if `additionalProperties` is `false` (explicitly or by inheritance) in a given type definition, then explicitly setting pattern properties in that definition is not allowed. If `additionalProperties` is `true` (or omitted) in a given type definition, then pattern properties are allowed and further restrict the additional properties allowed in that type. #### Object Type Specialization From 8932b73075e2c1f17c8b139ee3a4017332e20816 Mon Sep 17 00:00:00 2001 From: krishahn Date: Tue, 19 Apr 2016 14:03:52 -0700 Subject: [PATCH 129/241] copyedit Object Type Specialization --- versions/raml-10/raml-10.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/versions/raml-10/raml-10.md b/versions/raml-10/raml-10.md index 31f8dcd8..390dfc7d 100644 --- a/versions/raml-10/raml-10.md +++ b/versions/raml-10/raml-10.md @@ -618,7 +618,7 @@ Moreover, if `additionalProperties` is `false` (explicitly or by inheritance) in #### Object Type Specialization -You can declare object types that inherit from other object types a sub-type inherits all the properties of its parent type. In the example below, the type `Employee` inherits all properties of its parent type `Person`. +You can declare object types that inherit from other object types. A sub-type inherits all the properties of its parent type. In the following example, the type `Employee` inherits all properties of its parent type `Person`. ```yaml #%RAML 1.0 @@ -636,7 +636,7 @@ types: type: string ``` -Any sub-types can override properties defined in its parent types with the following two restrictions: 1) if a property is required in the parent type, it cannot be made optional in the sub-type, and 2) the type of an already defined property can only be changed to a narrower type (a type that specializes the parent type). +A sub-type can override properties of its parent type with the following restrictions: 1) a required property in the parent type cannot become optional in the sub-type, and 2) the type declaration of a defined property in the parent type cannot widen in the sub-type. Changes that narrow the type (specialize the parent type) are allowed. #### Using Discriminator From e3e946571cbf61ccc4d6fb3deb15239d074a3666 Mon Sep 17 00:00:00 2001 From: krishahn Date: Tue, 19 Apr 2016 14:55:52 -0700 Subject: [PATCH 130/241] copyedits of Using Discriminator --- versions/raml-10/raml-10.md | 18 +++++++++--------- 1 file changed, 9 insertions(+), 9 deletions(-) diff --git a/versions/raml-10/raml-10.md b/versions/raml-10/raml-10.md index 31f8dcd8..3e027938 100644 --- a/versions/raml-10/raml-10.md +++ b/versions/raml-10/raml-10.md @@ -640,11 +640,11 @@ Any sub-types can override properties defined in its parent types with the follo #### Using Discriminator -When payloads contain ambiguous types (achieved via unions or inheritance) it is often impossible to discriminate the concrete type of an individual object at runtime (for example when deserializing the payload into a statically typed language). +When payloads contain ambiguous types due to unions or inheritance, it is often impossible to discriminate the concrete type of an individual object at runtime. For example, when deserializing the payload into a statically typed language, this problem can occur. -A RAML processor may provide an implementation that automatically select a concrete type from a set of possible types, but one of the simplest options is to actually store some unique value associated with the type inside the object. +A RAML processor might provide an implementation that automatically selects a concrete type from a set of possible types, but a simpler alternative is to store some unique value associated with the type inside the object. -The `discriminator` facet allows you to set the name of an object property which will be used to discriminate the concrete type, and `discriminatorValue` stores the actual value that may identify the type of an individual object. By default, the value of `discriminatorValue` is the name of the type. +You set the name of an object property using the `discriminator` facet. The name of the object property is used to discriminate the concrete type. The `discriminatorValue` stores the actual value that might identify the type of an individual object. By default, the value of `discriminatorValue` is the name of the type. Here's an example that illustrates how to use `discriminator`: @@ -658,11 +658,11 @@ types: properties: kind: string # contains name of the kind of a `Person` instance name: string - Employee: # kind may equal to `Employee; default value for `discriminatorValue` + Employee: # kind can equal `Employee`; default value for `discriminatorValue` type: Person properties: employeeId: integer - User: # kind may equal to `User`; default value for `discriminatorValue` + User: # kind can equal `User`; default value for `discriminatorValue` type: Person properties: userId: integer @@ -678,7 +678,7 @@ data: kind: Employee ``` -You can also override the default for `discriminatorValue` for each individual concrete class. In the following example we will replace the default by their lowercase versions using `discriminatorValue`: +You can also override the default for `discriminatorValue` for each individual concrete class. The following example replaces the default value of `discriminatorValue` in initial caps with lowercase: ```yaml #%RAML 1.0 @@ -712,10 +712,10 @@ data: kind: employee ``` -Neither `discriminator` nor `discriminatorValue` are allowed to be defined for any inline type declarations or union types. +Neither `discriminator` nor `discriminatorValue` can be defined for any inline type declarations or union types. ```yaml -# valid when ever there is a key name that can identify a type +# valid whenever there is a key name that can identify a type types: Device: discriminator: kind @@ -724,7 +724,7 @@ types: ``` ```yaml -# invalid in any inline type declarations +# invalid in any inline type declaration application/json: discriminator: kind properties: From 0f8afc54084076513ad252e635ed17efdabb3a83 Mon Sep 17 00:00:00 2001 From: krishahn Date: Tue, 19 Apr 2016 15:45:06 -0700 Subject: [PATCH 131/241] copyedit Array Types section --- versions/raml-10/raml-10.md | 12 ++++++------ 1 file changed, 6 insertions(+), 6 deletions(-) diff --git a/versions/raml-10/raml-10.md b/versions/raml-10/raml-10.md index 31f8dcd8..834212db 100644 --- a/versions/raml-10/raml-10.md +++ b/versions/raml-10/raml-10.md @@ -740,16 +740,16 @@ PersonOrDog: ### Array Types -Array Types are declared by either using the array qualifier `[]` at the end of a [type expression](#type-expressions) or `array` as the value of a `type` node. If you are defining a top-level array type (like the example below), you can pass the following additional facets to further restrict its behavior. +Array types are declared by using either the array qualifier `[]` at the end of a [type expression](#type-expressions) or `array` as the value of a `type` node. If you are defining a top-level array type, such as the `Emails` in the examples below, you can declare the following facets in addition to those previously described to further restrict behavior of the array type. | Facet | Description | |:----------|:----------| | uniqueItems? | Boolean value that indicates if items in the array MUST be unique. -| items? | Indicates what type all items in the array inherit from. Can be a reference to an existing type or an inline [type declaration](#type-declaration) -| minItems? | Minimum amount of items in array. Value MUST be equal or greater than 0.

      **Default:** `0`. -| maxItems? | Maximum amount of items in array. Value MUST be equal or greater than 0.

      **Default:** `2147483647`. +| items? | Indicates the type all items in the array are inherited from. Can be a reference to an existing type or an inline [type declaration](#type-declaration). +| minItems? | Minimum amount of items in array. Value MUST be equal to or greater than 0.

      **Default:** `0`. +| maxItems? | Maximum amount of items in array. Value MUST be equal to or greater than 0.

      **Default:** `2147483647`. -So following are both valid examples: +The following examples are valid: ```yaml types: @@ -778,7 +778,7 @@ types: uniqueItems: true ``` -Using `Email[]` is equivalent to use `type: array` and specifically define the type each items in the array inherit from using the `items` facet. +Using `Email[]` is equivalent to using `type: array`. The `items` facet defines the Email type as the one each array item inherits from. ### Scalar Types From 71d5b37c2f70127674300982f48d32ea8a471f48 Mon Sep 17 00:00:00 2001 From: krishahn Date: Tue, 19 Apr 2016 15:51:01 -0700 Subject: [PATCH 132/241] extra space, restore both examples are valid --- versions/raml-10/raml-10.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/versions/raml-10/raml-10.md b/versions/raml-10/raml-10.md index 834212db..9445aca5 100644 --- a/versions/raml-10/raml-10.md +++ b/versions/raml-10/raml-10.md @@ -745,11 +745,11 @@ Array types are declared by using either the array qualifier `[]` at the end of | Facet | Description | |:----------|:----------| | uniqueItems? | Boolean value that indicates if items in the array MUST be unique. -| items? | Indicates the type all items in the array are inherited from. Can be a reference to an existing type or an inline [type declaration](#type-declaration). +| items? | Indicates the type all items in the array are inherited from. Can be a reference to an existing type or an inline [type declaration](#type-declaration). | minItems? | Minimum amount of items in array. Value MUST be equal to or greater than 0.

      **Default:** `0`. | maxItems? | Maximum amount of items in array. Value MUST be equal to or greater than 0.

      **Default:** `2147483647`. -The following examples are valid: +Both of the following examples are valid: ```yaml types: From 3dcbc339ac45a2c56841724d1d5b6a44c8e25292 Mon Sep 17 00:00:00 2001 From: krishahn Date: Tue, 19 Apr 2016 15:55:19 -0700 Subject: [PATCH 133/241] add ticks --- versions/raml-10/raml-10.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/versions/raml-10/raml-10.md b/versions/raml-10/raml-10.md index 9445aca5..5b600019 100644 --- a/versions/raml-10/raml-10.md +++ b/versions/raml-10/raml-10.md @@ -778,7 +778,7 @@ types: uniqueItems: true ``` -Using `Email[]` is equivalent to using `type: array`. The `items` facet defines the Email type as the one each array item inherits from. +Using `Email[]` is equivalent to using `type: array`. The `items` facet defines the `Email` type as the one each array item inherits from. ### Scalar Types From 25307e56797cb5265d0955774077bb0b1f6d132f Mon Sep 17 00:00:00 2001 From: krishahn Date: Tue, 19 Apr 2016 16:02:34 -0700 Subject: [PATCH 134/241] a few nits in scalar types section --- versions/raml-10/raml-10.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/versions/raml-10/raml-10.md b/versions/raml-10/raml-10.md index 31f8dcd8..88f59031 100644 --- a/versions/raml-10/raml-10.md +++ b/versions/raml-10/raml-10.md @@ -782,7 +782,7 @@ Using `Email[]` is equivalent to use `type: array` and specifically define the t ### Scalar Types -RAML defines a set of built-in scalar types and each of them has a predefined set of restrictions. All these types, except the file type, may have an additional `enum` facet. +RAML defines a set of built-in scalar types, each of which has a predefined set of restrictions. All types, except the file type, can have an additional `enum` facet. | Facet | Description | |:--------|:------------| From d9a9bc887412dbe772e3f25ed780be6368a80593 Mon Sep 17 00:00:00 2001 From: krishahn Date: Tue, 19 Apr 2016 16:34:13 -0700 Subject: [PATCH 135/241] a few minor edits to the String, Number, Integer, and Boolean sections --- versions/raml-10/raml-10.md | 14 +++++++------- 1 file changed, 7 insertions(+), 7 deletions(-) diff --git a/versions/raml-10/raml-10.md b/versions/raml-10/raml-10.md index 31f8dcd8..be6e81f2 100644 --- a/versions/raml-10/raml-10.md +++ b/versions/raml-10/raml-10.md @@ -809,9 +809,9 @@ A JSON string with the following additional facets: | Facet | Description | |:--------|:------------| -| pattern? | Regular expression that this string should pass. -| minLength? | Minimum length of the string. Value MUST be equal or greater than 0.

      **Default:** `0` -| maxLength? | Maximum length of the string. Value MUST be equal or greater than 0.

      **Default:** `2147483647` +| pattern? | Regular expression that this string should match. +| minLength? | Minimum length of the string. Value MUST be equal to or greater than 0.

      **Default:** `0` +| maxLength? | Maximum length of the string. Value MUST be equal to or greater than 0.

      **Default:** `2147483647` Example: @@ -829,10 +829,10 @@ Any JSON number including [integer](#integer) with the following additional face | Facet | Description | |:--------|:------------| -|minimum? | (applicable only for parameters of type number or integer) The minimum attribute specifies the parameter's minimum value. -|maximum? | (applicable only for parameters of type number or integer) The maximum attribute specifies the parameter's maximum value. -|format? | Identifies the format of the value. The value MUST be one of the following: int32, int64, int, long, float, double, int16, int8 -|multipleOf? | A numeric instance is valid against "multipleOf" if the result of the division of the instance by this keyword's value is an integer. +|minimum? | The minimum value of the parameter. Applicable only to parameters of type number or integer. +|maximum? | The maximum value of the parameter. Applicable only to parameters of type number or integer. +|format? | The format of the value. The value MUST be one of the following: int32, int64, int, long, float, double, int16, int8 +|multipleOf? | A numeric instance is valid against "multipleOf" if the result of dividing the instance by this keyword's value is an integer. Example: From 666528a581aa183d8c68823c1b14008f718b71c9 Mon Sep 17 00:00:00 2001 From: krishahn Date: Tue, 19 Apr 2016 17:23:28 -0700 Subject: [PATCH 136/241] copyedit Date section --- versions/raml-10/raml-10.md | 14 +++++++------- 1 file changed, 7 insertions(+), 7 deletions(-) diff --git a/versions/raml-10/raml-10.md b/versions/raml-10/raml-10.md index 31f8dcd8..8e00c94f 100644 --- a/versions/raml-10/raml-10.md +++ b/versions/raml-10/raml-10.md @@ -876,12 +876,12 @@ The following date type representations MUST be supported: | Type | Description | |:-----|:------------| -| date-only | the "full-date" notation of [RFC3339](http://xml2rfc.ietf.org/public/rfc/html/rfc3339.html#anchor14), namely `yyyy-mm-dd` (no implications about time or timezone-offset) -| time-only | the "partial-time" notation of [RFC3339](http://xml2rfc.ietf.org/public/rfc/html/rfc3339.html#anchor14), namely hh:mm:ss\[.ff...\] (no implications about date or timezone-offset) -| datetime-only | combined date-only and time-only with a separator of "T", namely yyyy-mm-ddThh:mm:ss\[.ff...\] (no implications about timezone-offset) -| datetime | a timestamp, either in the "date-time" notation of [RFC3339](http://xml2rfc.ietf.org/public/rfc/html/rfc3339.html#anchor14), if _format_ is omitted or is set to `rfc3339`, or in the format defined in [RFC2616](https://www.ietf.org/rfc/rfc2616.txt), if _format_ is set to `rfc2616` +| date-only | The "full-date" notation of [RFC3339](http://xml2rfc.ietf.org/public/rfc/html/rfc3339.html#anchor14), namely `yyyy-mm-dd`. Does not support time or time zone-offset notation. +| time-only | The "partial-time" notation of [RFC3339](http://xml2rfc.ietf.org/public/rfc/html/rfc3339.html#anchor14), namely hh:mm:ss\[.ff...\]. Does not support date or time zone-offset notation. +| datetime-only | Combined date-only and time-only with a separator of "T", namely yyyy-mm-ddThh:mm:ss\[.ff...\]. Does not support a time zone offset. +| datetime | A timestamp in one of the following formats: if the _format_ is omitted or set to `rfc3339`, uses the "date-time" notation of [RFC3339](http://xml2rfc.ietf.org/public/rfc/html/rfc3339.html#anchor14); if _format_ is set to `rfc2616`, uses the format defined in [RFC2616](https://www.ietf.org/rfc/rfc2616.txt). -The additional property _format_ MUST only be available when the type equals to _datetime_ and the value MUST be either `rfc3339` or `rfc2616`. Any other values are invalid. +The additional property _format_ MUST be available only when the type equals _datetime_, and the value MUST be either `rfc3339` or `rfc2616`. Any other values are invalid. ```yaml types: @@ -897,11 +897,11 @@ types: created: type: datetime example: 2016-02-28T16:41:41.090Z - format: rfc3339 # the default, so needn't be specified + format: rfc3339 # the default, so no need to specify If-Modified-Since: type: datetime example: Sun, 28 Feb 2016 16:41:41 GMT - format: rfc2616 # this time it's required as otherwise the example is in an invalid format + format: rfc2616 # this time it's required, otherwise, the example format is invalid ``` #### File From d7fc7e872df94e21d4f8d2af61cfd4400483a016 Mon Sep 17 00:00:00 2001 From: Christian Vogel Date: Wed, 20 Apr 2016 09:16:53 +0100 Subject: [PATCH 137/241] changed 'type node' to 'type facet' for a consistent language --- versions/raml-10/raml-10.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/versions/raml-10/raml-10.md b/versions/raml-10/raml-10.md index 5b600019..c11bfb1a 100644 --- a/versions/raml-10/raml-10.md +++ b/versions/raml-10/raml-10.md @@ -740,7 +740,7 @@ PersonOrDog: ### Array Types -Array types are declared by using either the array qualifier `[]` at the end of a [type expression](#type-expressions) or `array` as the value of a `type` node. If you are defining a top-level array type, such as the `Emails` in the examples below, you can declare the following facets in addition to those previously described to further restrict behavior of the array type. +Array types are declared by using either the array qualifier `[]` at the end of a [type expression](#type-expressions) or `array` as the value of a `type` facet. If you are defining a top-level array type, such as the `Emails` in the examples below, you can declare the following facets in addition to those previously described to further restrict behavior of the array type. | Facet | Description | |:----------|:----------| From c40ad6223a0d90de07245b870b47f5b542b7a55d Mon Sep 17 00:00:00 2001 From: Christian Vogel Date: Wed, 20 Apr 2016 10:21:44 +0100 Subject: [PATCH 138/241] improved inner elements section and moved it into the xml and json related section --- versions/raml-10/raml-10.md | 36 +++++++++++++----------------------- 1 file changed, 13 insertions(+), 23 deletions(-) diff --git a/versions/raml-10/raml-10.md b/versions/raml-10/raml-10.md index 8c6e1d7e..0fd48bc3 100644 --- a/versions/raml-10/raml-10.md +++ b/versions/raml-10/raml-10.md @@ -1212,6 +1212,19 @@ XML schema MUST NOT be used where the media type does not allow XML-formatted da Please note that the properties "schemas" and "types" are completely synonymous, so are "schema" and "type" for compatibility with RAML 0.8, but "schemas" and "schema" are deprecated. API definitions should use "types" and "type", as "schemas" and "schema" may be removed in a future RAML version. +#### References to Inner Elements + +Sometimes it is necessary to refer to an element defined in a schema. RAML supports that by using URL fragments like in the example below. + +```yaml +type: !include elements.xsd#Foo +``` + +Referencing an inner element of a schema is equivalent to referencing a top level element. The structural restrictions on referencing an inner element are the same as those on referencing other elements. This version of RAML specification supports referencing any inner elements in JSON schemas that are valid schemas, and any globally defined elements and complex types in XML schemas. There are only a few restrictions: + +* Validation of any XML or JSON instance against inner elements follows the same restrictions than the validation against a regular XML or JSON schema. +* Referencing complex types inside an XSD is valid to determine the structure of an XML instance, but since they do not define a name for the top-level XML element, they can not be used for serializing an XML instance + ### Multiple Inheritance RAML Types support multiple inheritance for object types. This is achieved by passing a sequence of types: @@ -3013,29 +3026,6 @@ traits: type: number ``` -#### References to inner elements of external files - -RAML 1.0 supports referring to inner elements of included schemas by using URL fragments. - - -```yaml -schema: !include elements.xsd#Foo -``` - -```yaml -/id: !include myContent.raml#feature -``` - -Dereferencing a fragment of a JSON schema is supported as described in the JSON Schema dereferencing rules in Chapter 7 of [_JSON Schema: core definitions and terminology_](http://json-schema.org/latest/json-schema-core.html) - -Dereferencing a fragment of an XSD is supported as described in section "3.15.2.2 References to Schema Components from Elsewhere" of [_XML Schema Part 1: Structures Second Edition_](http://www.w3.org/TR/xmlschema-1/). However, you can also refer to a named type in an XSD schema. - -Referencing an inner element of a schema is equivalent to referencing a top level element. The structural restrictions on referencing an inner element are the same as those on referencing other elements. This version of RAML specification supports references to elements of schemas in the following cases: - -* Referencing an element of a JSON schema in any context. The name of top level XML element of data that is serialized to an XML payload is not defined. -* Referencing an element of an XSD in any context. -* Referencing XSD complex types to determine the inner structure of payload. The name of top level XML element of data that is serialized to an XML payload is not defined. - ### Libraries RAML libraries are used to combine any collection of data type declarations, resource type declarations, trait declarations, and security scheme declarations into modular, externalized, reusable groups. While libraries are meant to allow definition of common declarations in external documents which are then included where needed, they may also be defined inline. From 91e184e6bf4062b1bbefcd082965fe7a7054def1 Mon Sep 17 00:00:00 2001 From: Kris Hahn Date: Wed, 20 Apr 2016 06:48:43 -0700 Subject: [PATCH 139/241] Update raml-10.md reviewed and made a few minor edits --- versions/raml-10/raml-10.md | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/versions/raml-10/raml-10.md b/versions/raml-10/raml-10.md index 0fd48bc3..88627bd3 100644 --- a/versions/raml-10/raml-10.md +++ b/versions/raml-10/raml-10.md @@ -1214,16 +1214,16 @@ Please note that the properties "schemas" and "types" are completely synonymous, #### References to Inner Elements -Sometimes it is necessary to refer to an element defined in a schema. RAML supports that by using URL fragments like in the example below. +Sometimes it is necessary to refer to an element defined in a schema. RAML supports that by using URL fragments as shown in the example below. ```yaml type: !include elements.xsd#Foo ``` -Referencing an inner element of a schema is equivalent to referencing a top level element. The structural restrictions on referencing an inner element are the same as those on referencing other elements. This version of RAML specification supports referencing any inner elements in JSON schemas that are valid schemas, and any globally defined elements and complex types in XML schemas. There are only a few restrictions: +Referencing an inner element of a schema is equivalent to referencing a top level element. The structural restrictions on referencing an inner element are the same as those on referencing other elements. This version of RAML specification supports referencing any inner elements in JSON schemas that are valid schemas, any globally defined elements, and complex types in XML schemas. There are only a few restrictions: -* Validation of any XML or JSON instance against inner elements follows the same restrictions than the validation against a regular XML or JSON schema. -* Referencing complex types inside an XSD is valid to determine the structure of an XML instance, but since they do not define a name for the top-level XML element, they can not be used for serializing an XML instance +* Validation of any XML or JSON instance against inner elements follows the same restrictions as the validation against a regular XML or JSON schema. +* Referencing complex types inside an XSD is valid to determine the structure of an XML instance, but since complex types do not define a name for the top-level XML element, these types cannot be used for serializing an XML instance. ### Multiple Inheritance From e902a5e1a48ca717475568fbd2997b43cb4e28e5 Mon Sep 17 00:00:00 2001 From: krishahn Date: Wed, 20 Apr 2016 06:58:30 -0700 Subject: [PATCH 140/241] awkward wording, inconsistent in structure with previous sentence --- versions/raml-10/raml-10.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/versions/raml-10/raml-10.md b/versions/raml-10/raml-10.md index 390dfc7d..05811745 100644 --- a/versions/raml-10/raml-10.md +++ b/versions/raml-10/raml-10.md @@ -636,7 +636,7 @@ types: type: string ``` -A sub-type can override properties of its parent type with the following restrictions: 1) a required property in the parent type cannot become optional in the sub-type, and 2) the type declaration of a defined property in the parent type cannot widen in the sub-type. Changes that narrow the type (specialize the parent type) are allowed. +A sub-type can override properties of its parent type with the following restrictions: 1) a required property in the parent type cannot become optional in the sub-type, and 2) the type declaration of a defined property in the parent type cannot become wider in the sub-type. Changes that narrow the type (specialize the parent type) are allowed. #### Using Discriminator From 0b6e85acc7b6d34ab16826ed838846be89020edf Mon Sep 17 00:00:00 2001 From: krishahn Date: Wed, 20 Apr 2016 07:34:01 -0700 Subject: [PATCH 141/241] move toward original wording for clarity, brevity --- versions/raml-10/raml-10.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/versions/raml-10/raml-10.md b/versions/raml-10/raml-10.md index 05811745..f45a7d99 100644 --- a/versions/raml-10/raml-10.md +++ b/versions/raml-10/raml-10.md @@ -636,7 +636,7 @@ types: type: string ``` -A sub-type can override properties of its parent type with the following restrictions: 1) a required property in the parent type cannot become optional in the sub-type, and 2) the type declaration of a defined property in the parent type cannot become wider in the sub-type. Changes that narrow the type (specialize the parent type) are allowed. +A sub-type can override properties of its parent type with the following restrictions: 1) a required property in the parent type cannot become optional in the sub-type, and 2) the type declaration of a defined property in the parent type can only become narrower (specialize the parent type) in the sub-type. #### Using Discriminator From d1a08c28acb0ccef66e69b2e2c8954cd1bb2dcde Mon Sep 17 00:00:00 2001 From: krishahn Date: Wed, 20 Apr 2016 07:45:42 -0700 Subject: [PATCH 142/241] re-incorporate the idea of the developer making the change --- versions/raml-10/raml-10.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/versions/raml-10/raml-10.md b/versions/raml-10/raml-10.md index f45a7d99..656771f1 100644 --- a/versions/raml-10/raml-10.md +++ b/versions/raml-10/raml-10.md @@ -636,7 +636,7 @@ types: type: string ``` -A sub-type can override properties of its parent type with the following restrictions: 1) a required property in the parent type cannot become optional in the sub-type, and 2) the type declaration of a defined property in the parent type can only become narrower (specialize the parent type) in the sub-type. +A sub-type can override properties of its parent type with the following restrictions: 1) a required property in the parent type cannot be changed to optional in the sub-type, and 2) the type declaration of a defined property in the parent type can only be changed to a narrower type (a specialization of the parent type) in the sub-type. #### Using Discriminator From da616d5ef082688d9d351f0c5001d0c36434a352 Mon Sep 17 00:00:00 2001 From: Christian Vogel Date: Wed, 20 Apr 2016 18:17:46 +0100 Subject: [PATCH 143/241] incorporated feedback --- versions/raml-10/raml-10.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/versions/raml-10/raml-10.md b/versions/raml-10/raml-10.md index 68d050b6..723a3797 100644 --- a/versions/raml-10/raml-10.md +++ b/versions/raml-10/raml-10.md @@ -155,7 +155,7 @@ The following table enumerates the possible properties at the root of a RAML doc | uses? | Imported external [libraries](#libraries) for use within the API. | /<relativeUri>? | The resources of the API, identified as relative URIs that begin with a slash (/). A [resource property](#resources-and-nested-resources) is one that begins with the slash and is either at the root of the API definition or a child of a resource property. For example, /users and /{groupId}. -The "schemas" and "types" nodes are mutually exclusive and synonymous: processors MUST NOT allow both to be specified, explicitly or implicitly, at the root-level of an API definition. We recommended using the "types" node instead of "schemas" because the schemas alias is deprecated and might be removed in a future RAML version. Also, the "types" node supports XML and JSON schemas. +The "schemas" and "types" nodes are mutually exclusive and synonymous: processors MUST NOT allow both to be specified at the root-level of an API definition. We recommended using the "types" node instead of "schemas" because the schemas alias is deprecated and might be removed in a future RAML version. ### User Documentation From 4d1e5f480646115b4f3d7004458a867f5cc0ab62 Mon Sep 17 00:00:00 2001 From: Christian Vogel Date: Wed, 20 Apr 2016 19:48:31 +0100 Subject: [PATCH 144/241] minor fixes and improvements to raml-0.8.md file that has been introduced in couple of PRs --- versions/raml-08/raml-08.md | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/versions/raml-08/raml-08.md b/versions/raml-08/raml-08.md index a15ff74c..fcf8660b 100644 --- a/versions/raml-08/raml-08.md +++ b/versions/raml-08/raml-08.md @@ -1115,7 +1115,7 @@ This example shows a 503 error response that includes a custom header. description: | The number of seconds to wait before you can attempt to make a request again. type: integer - required: yes + required: true minimum: 1 maximum: 3600 example: 34 @@ -1187,7 +1187,7 @@ traits: required: true ``` -The following example builds on the previous one, but the the resource types and traits are defined in external files that are included by using the RAML !include data type. +The following example builds on the previous one, but the resource types and traits are defined in external files that are included by using the RAML !include data type. ```yaml #%RAML 0.8 @@ -1262,8 +1262,8 @@ title: Example API version: v1 mediaType: application/json schemas: - users: !include schemas/users.json - user: !include schemas/user.json + - users: !include schemas/users.json + - user: !include schemas/user.json resourceTypes: - collection: get: From 982ddfd8d0ed8dda43193f9ec0ffd00df7fd2393 Mon Sep 17 00:00:00 2001 From: Christian Vogel Date: Wed, 20 Apr 2016 20:26:14 +0100 Subject: [PATCH 145/241] modified sentence according to Uri's comments --- versions/raml-10/raml-10.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/versions/raml-10/raml-10.md b/versions/raml-10/raml-10.md index 88627bd3..b57705f7 100644 --- a/versions/raml-10/raml-10.md +++ b/versions/raml-10/raml-10.md @@ -1220,7 +1220,7 @@ Sometimes it is necessary to refer to an element defined in a schema. RAML suppo type: !include elements.xsd#Foo ``` -Referencing an inner element of a schema is equivalent to referencing a top level element. The structural restrictions on referencing an inner element are the same as those on referencing other elements. This version of RAML specification supports referencing any inner elements in JSON schemas that are valid schemas, any globally defined elements, and complex types in XML schemas. There are only a few restrictions: +When referencing an inner element of a schema, a RAML processor MUST validate an instance against that particular element. The structural restrictions on referencing an inner element are the same as those on referencing other elements. This version of RAML specification supports referencing any inner elements in JSON schemas that are valid schemas, any globally defined elements, and complex types in XML schemas. There are only a few restrictions: * Validation of any XML or JSON instance against inner elements follows the same restrictions as the validation against a regular XML or JSON schema. * Referencing complex types inside an XSD is valid to determine the structure of an XML instance, but since complex types do not define a name for the top-level XML element, these types cannot be used for serializing an XML instance. From dffb32dd82c26a3b992265ea1f9936b7fc83ddab Mon Sep 17 00:00:00 2001 From: krishahn Date: Wed, 20 Apr 2016 17:17:02 -0700 Subject: [PATCH 146/241] copyedit file section --- versions/raml-10/raml-10.md | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/versions/raml-10/raml-10.md b/versions/raml-10/raml-10.md index b56aaf02..8b90293a 100644 --- a/versions/raml-10/raml-10.md +++ b/versions/raml-10/raml-10.md @@ -908,13 +908,13 @@ types: #### File -The ​**file**​ type can be used to constrain the content to send through forms. When it is used in the context of web forms it SHOULD be represented as a valid file upload, and in JSON representation, it SHOULD be represented as a base64 encoded string with a file content. +The ​**file**​ type can constrain the content to send through forms. When this type is used in the context of web forms it SHOULD be represented as a valid file upload in JSON format. File content SHOULD be a base64-encoded string. | Facet | Description | |:--------|:------------| -| fileTypes? | List of valid content-types for the file. The file type `*/*` should be a valid value. -| minLength? | Specifies the parameter value's minimum number of bytes. Value MUST be equal or greater than 0.

      **Default:** `0` -| maxLength? | Specifies the parameter value's maximum number of bytes. Value MUST be equal or greater than 0.

      **Default:** `2147483647` +| fileTypes? | A list of valid content-types in `*/*` notation for the file. +| minLength? | Specifies the minimum number of bytes for a parameter value. The value MUST be equal to or greater than 0.

      **Default:** `0` +| maxLength? | Specifies the maximum number of bytes for a parameter value. The value MUST be equal to or greater than 0.

      **Default:** `2147483647` ### User-defined Facets From a42e22a47462d94a92ea3d204bb2544ea8d43812 Mon Sep 17 00:00:00 2001 From: krishahn Date: Wed, 20 Apr 2016 21:54:47 -0700 Subject: [PATCH 147/241] copyedits of User-defined facets plus link text correction --- versions/raml-10/raml-10.md | 14 +++++++------- 1 file changed, 7 insertions(+), 7 deletions(-) diff --git a/versions/raml-10/raml-10.md b/versions/raml-10/raml-10.md index b56aaf02..b579a724 100644 --- a/versions/raml-10/raml-10.md +++ b/versions/raml-10/raml-10.md @@ -428,7 +428,7 @@ A type declaration can extend a built-in type or other custom type, or add more | displayName? | An alternate, human-friendly name for the type | description? | A substantial, human-friendly description of the type | (<annotationName>)? | [Annotations](#annotations) to be applied to this type. An annotation is a property having a key that begins with "(" and ends with ")". The text enclosed in parentheses is the annotation name. -| facets? | A map of additional, user-defined restrictions that will be inherited and applied by any extending subtype. See section [User defined Facets](#user-defined-facets) for more information. +| facets? | A map of additional, user-defined restrictions that will be inherited and applied by any extending subtype. See section [User-defined Facets](#user-defined-facets) for more information. | xml? | The capability to configure [XML serialization of this type instance](#xml-serialization-of-type-instances). The "schema" and "type" facets are mutually exclusive and synonymous: processors MUST NOT allow both to be specified, explicitly or implicitly, inside the same type declaration. Therefore, the following examples are invalid: @@ -918,15 +918,15 @@ The ​**file**​ type can be used to constrain the content to send through for ### User-defined Facets -Facets express various additional restrictions which types impose on their instances, such as the optional `minimum` and `maximum` facets for numbers, or the `enum` facet for scalars. RAML provides a way to declare additional user-defined facets for any data type. +Facets express various additional restrictions beyond those which types impose on their instances, such as the optional `minimum` and `maximum` facets for numbers, or the `enum` facet for scalars. In addition to the built-in facets, RAML provides a way to declare user-defined facets for any data type. -User-defined facets are defined using the OPTIONAL `facets` property on a type declaration. Its value is a map whose keys name the user-defined facets and whose corresponding values define the concrete values which the corresponding facet may take, following the same syntax as [property declaration](#property-declarations). That is, a facet declaration in the declaration of a type specifies the concrete values which subtypes may use for that facet to restrict instances of those subtypes. Note that this implies that user-defined facets on a type do not restrict instances of that type but rather only instances of subtypes of that type. +The user-defined facet is declared using the OPTIONAL `facets` property in a type declaration. The value of the `facets` property is a map. The key names the user-defined facet. The corresponding value defines the concrete value that the respective facet can take. The syntax of a [property declaration](#property-declarations) and user-defined facet declaration are the same. A facet restricts instances of a subtype, not its type, based on the concrete value defined in the facet declaration. -Facet names MUST NOT begin with open parentheses, to disambiguate them from annotations. User-defined facet names on a type MUST NOT match built-in facets on that type, nor facet names of any ancestor type in the type's inheritance chain. +Facet names MUST NOT begin with open parenthesis, to disambiguate the names from annotations. User-defined facet names on a type MUST NOT match built-in facets on that type, nor facet names of any ancestor type in the inheritance chain of the type. If a facet of a type is declared as required, then any subtype of that type MUST define a value for that facet. -Here is an example which defines the capability to add restrictions on dates that indicate they may not fall on holidays: +Here is an example that defines the capability to restrict dates to those that do not fall on holidays: ```yaml #%RAML 1.0 @@ -942,9 +942,9 @@ types: noHolidays: true ``` -In the above example, the possibility of restricting date instances based on whether they fall on holidays is introduced by declaring the `noHolidays` facet and defining its values to be boolean. Then instances of any inheriting type, such as the `PossibleMeetingDate` type, must have values that do not fall on holidays. +In this example, declaring the `noHolidays` facet and defining its values to be boolean makes it possible to restrict date instances that fall on holidays. Instances of any inheriting type, such as the `PossibleMeetingDate` type, must have values that do not fall on holidays. -Because user-defined facets are by definition not built into this RAML specification, and hence their semantic may not be understood by all RAML processors, a RAML processor may or may not choose to use user-defined facets on a type in validating instances of that type. In the example above, a RAML processor may or may not assign a meaning to `noHolidays` and so may choose to ignore the `noHolidays: true` value in validating instances of `PossibleMeetingDate`. +User-defined facets by definition are not built into this RAML specification, and hence their semantic might not be understood by all RAML processors. Consequently, a RAML processor may or may not choose to use user-defined facets on a type in validating instances of that type. In the example above, a RAML processor may or may not assign a meaning to `noHolidays`, and therefore, may choose to ignore the `noHolidays: true` value in validating instances of `PossibleMeetingDate`. ### Determine Default Types From 01a24cafbf7911a5cd8d7b9020b3ea81ea759e20 Mon Sep 17 00:00:00 2001 From: krishahn Date: Wed, 20 Apr 2016 22:20:56 -0700 Subject: [PATCH 148/241] copyedit Determine Default Types --- versions/raml-10/raml-10.md | 78 ++++++++++++++++++------------------- 1 file changed, 39 insertions(+), 39 deletions(-) diff --git a/versions/raml-10/raml-10.md b/versions/raml-10/raml-10.md index b56aaf02..9e79edc1 100644 --- a/versions/raml-10/raml-10.md +++ b/versions/raml-10/raml-10.md @@ -950,57 +950,57 @@ Because user-defined facets are by definition not built into this RAML specifica A RAML processor must be able to determine the default type of a type declaration by using the following rules: -* If, and only if, a type declaration contains a `properties` facet; the default type is `object`. For example (based on this rule): +* If, and only if, a type declaration contains a `properties` facet, then the default type is `object`. The following snippet exemplifies this rule: -```yaml -types: - Person: - type: object - properties: -``` + ```yaml + types: + Person: + type: object + properties: + ``` -can also be written + This rule can also be written as follows: -```yaml -types: - Person: - # default type is `object`, no need to explicitly define it - properties: -``` + ```yaml + types: + Person: + # default type is `object`, no need to explicitly define it + properties: + ``` -* If, and only if, a type declaration contains neither a `properties` facet nor a `type` or `schema` facet, then the default type is `string`. For example (based on this rule): +* If, and only if, a type declaration contains neither a `properties` facet nor a `type` or `schema` facet, then the default type is `string`. The following snippet exemplifies this rule: -```yaml -types: - Person: - properties: - name: # no type or schema necessary since the default type is `string` -``` + ```yaml + types: + Person: + properties: + name: # no type or schema necessary since the default type is `string` + ``` * The default type `any` is applied to any `body` node that does not contain `properties`, `type`, or `schema`. For example: -```yaml -body: - application/json: - # default type is `any` -``` + ```yaml + body: + application/json: + # default type is `any` + ``` -Or in case that a default media type has been defined + Or, if a default media type has been defined, no need to declare it here: -```yaml -body: - # default type is `any` -``` + ```yaml + body: + # default type is `any` + ``` -Of course, each rule can be overridden by explicitly define a type. For example: + Of course, each rule can be overridden by explicitly defining a type. For example: -```yaml -types: - Person: - properties: - name: - type: number -``` + ```yaml + types: + Person: + properties: + name: + type: number + ``` ### Type Expressions From a8351a6e6f6ab248e3f16cc16b84b638ea5d161e Mon Sep 17 00:00:00 2001 From: krishahn Date: Wed, 20 Apr 2016 22:49:59 -0700 Subject: [PATCH 149/241] copyedit Type Expressions --- versions/raml-10/raml-10.md | 10 +++++----- 1 file changed, 5 insertions(+), 5 deletions(-) diff --git a/versions/raml-10/raml-10.md b/versions/raml-10/raml-10.md index b56aaf02..7ec526c3 100644 --- a/versions/raml-10/raml-10.md +++ b/versions/raml-10/raml-10.md @@ -1004,7 +1004,7 @@ types: ### Type Expressions -So far we have only used simple type identifiers to refer to other Types (ex: string, object, Person). Type Expressions provide a powerful way of referring to, and even defining, types. Type Expressions can be used wherever a type is expected. The simplest Type Expression is just the name of a type. But Type expressions also allow you to express Type Unions, Arrays, and maps amongst other things. +Earlier, this specification used only simple type identifiers to refer to types, such as string, object, and Person. Type expressions provide a powerful way of referring to, and even defining, types. Type expressions can be used wherever a type is expected. The simplest type expression is just the name of a type. Using type expressions, you can devise type unions, arrays, maps, and other things. |Expression | Description | |:--------|:------------| @@ -1012,10 +1012,10 @@ So far we have only used simple type identifiers to refer to other Types (ex: st | `Person[]` | An array of Person objects | `string[]` | An array of string scalars | `string[][]` | A bi-dimensional array of string scalars -| `string | Person` | Union type made of members of string OR Person -| `(string | Person)[]` | An array of the above type +| `string | Person` | A union type made of members of string OR Person +| `(string | Person)[]` | An array of the type shown above -Type Expressions can be used wherever a Type is expected: +Type expressions can be used wherever a type is expected: ```yaml #%RAML 1.0 @@ -1067,7 +1067,7 @@ types: type: ( Phone | Notebook )[] ``` -The example above is actually declaring a "Type Alias", which gives a more readable name ( Devices ) to a type defined via a complex type expression ( in this case an array of a union of the types Phone and Notebook ). You can use this technique to give simple names to complex types. Type Aliases can also hold extra properties. For example a description and annotations. +This example is actually declaring a "type alias", which gives a more readable name ( Devices ) to a type defined using a complex type expression. In this case, the type expression consists of an array of a union of the types Phone and Notebook. You can use this technique to give simple names to complex types. Type aliases can also hold extra properties, for example a description and annotations. #### Grammar From f1fe44d0e548d76dc8e04fdad7cbb816c1e0b9ff Mon Sep 17 00:00:00 2001 From: krishahn Date: Wed, 20 Apr 2016 22:54:38 -0700 Subject: [PATCH 150/241] minor edit --- versions/raml-10/raml-10.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/versions/raml-10/raml-10.md b/versions/raml-10/raml-10.md index 7ec526c3..573e073c 100644 --- a/versions/raml-10/raml-10.md +++ b/versions/raml-10/raml-10.md @@ -1008,7 +1008,7 @@ Earlier, this specification used only simple type identifiers to refer to types, |Expression | Description | |:--------|:------------| -| `Person` | The simplest type expression: A single Type +| `Person` | The simplest type expression: A single type | `Person[]` | An array of Person objects | `string[]` | An array of string scalars | `string[][]` | A bi-dimensional array of string scalars From 537e82b013a3ef03caf7bd9a9e583494cb997d1d Mon Sep 17 00:00:00 2001 From: Christian Vogel Date: Thu, 21 Apr 2016 16:04:36 +0100 Subject: [PATCH 151/241] added null type to the spec according to issue #394 --- versions/raml-10/raml-10.md | 49 ++++++++++++++++++++++++++++++++++--- 1 file changed, 45 insertions(+), 4 deletions(-) diff --git a/versions/raml-10/raml-10.md b/versions/raml-10/raml-10.md index 54fef283..0836ec21 100644 --- a/versions/raml-10/raml-10.md +++ b/versions/raml-10/raml-10.md @@ -916,6 +916,45 @@ The ​**file**​ type can constrain the content to send through forms. When th | minLength? | Specifies the minimum number of bytes for a parameter value. The value MUST be equal to or greater than 0.

      **Default:** `0` | maxLength? | Specifies the maximum number of bytes for a parameter value. The value MUST be equal to or greater than 0.

      **Default:** `2147483647` +### Null Type +​ +RAML handles null data values in payloads, annotations, and other constructs. Nullable properties must be represented as a single `null` type, a union of the non-null and `null` types, or suffixing the type with a trailing question mark `?`. +In the following example, the type of an object and has two required properties, `name` and `comment`, both defaulting to type `string`. In `example`, `name` is assigned a string value, but comment is null and this is _not_ allowed because RAML expects a string. +```yaml +type: + properties: + name: + comment: +example: + name: Fred + comment: # Providing no value here is not allowed. +``` +The following example shows the assignment of the `null` type to `comment`: +​ +```yaml +type: + properties: + name: + comment: null +example: + name: Fred + comment: # Providing a value here is not allowed. +``` +The following example shows how to represent nullable properties using a union: +​ +```yaml +type: + properties: + name: + comment: string | null # equivalent to -> + # comment: string? +example: + name: Fred + comment: # Providing a value or not providing a value here is allowed. +``` + +Declaring the type of a property to be `null` causes a RAML processor to forbid an instance to have a value. + ### User-defined Facets Facets express various additional restrictions beyond those which types impose on their instances, such as the optional `minimum` and `maximum` facets for numbers, or the `enum` facet for scalars. In addition to the built-in facets, RAML provides a way to declare user-defined facets for any data type. @@ -2635,11 +2674,12 @@ The following is an example of various annotation type declarations and the appl title: Illustrating annotations mediaType: application/json annotationTypes: - experimental: - feedbackRequested: + deprecated: null + experimental: string | null + feedbackRequested: string? testHarness: type: string # This line may be omitted as it's the default type - badge: # This annotation type, too, allows string values + badge: # This annotation type, too, allows string values clearanceLevel: properties: level: @@ -2658,8 +2698,9 @@ annotationTypes: level: high signature: 230-ghtwvfrs1itr get: + (deprecated): (experimental): - (feedbackRequested): + (feedbackRequested): Feedback committed! responses: 200: ``` From c55443902a6aa7be3c3e285f3fc584c9fa64f73d Mon Sep 17 00:00:00 2001 From: Christian Vogel Date: Thu, 21 Apr 2016 17:02:03 +0100 Subject: [PATCH 152/241] changed multiple examples example to remove some confusion with old syntax and new syntax using 'content' and 'value' --- versions/raml-10/raml-10.md | 10 ++++++---- 1 file changed, 6 insertions(+), 4 deletions(-) diff --git a/versions/raml-10/raml-10.md b/versions/raml-10/raml-10.md index 54fef283..98ea3243 100644 --- a/versions/raml-10/raml-10.md +++ b/versions/raml-10/raml-10.md @@ -1272,11 +1272,13 @@ The following is an example of the value of an **examples** property: ```yaml message: # {key} - unique id + # example declaration title: Attention needed - content: You have been added to group 274 + body: You have been added to group 274 record: # {key} - unique id + # example declaration name: log item - value: permission check + comment: permission check ``` #### Single Example @@ -1289,7 +1291,7 @@ For example: ```yaml title: Attention needed -content: You have been added to group 274 +body: You have been added to group 274 ``` ##### The value is a map that contains the following additional facets @@ -1309,7 +1311,7 @@ For example: strict: false value: title: Attention needed - content: You have been added to group 274 + body: You have been added to group 274 ``` #### Example on how to define example/examples in RAML From 103656966956288b2ab1c2955236166369689751 Mon Sep 17 00:00:00 2001 From: Christian Vogel Date: Thu, 21 Apr 2016 18:28:18 +0100 Subject: [PATCH 153/241] fixed example for annotations --- versions/raml-10/raml-10.md | 5 +++-- 1 file changed, 3 insertions(+), 2 deletions(-) diff --git a/versions/raml-10/raml-10.md b/versions/raml-10/raml-10.md index 98ea3243..c5c48c97 100644 --- a/versions/raml-10/raml-10.md +++ b/versions/raml-10/raml-10.md @@ -1348,8 +1348,9 @@ types: application/json: type: Org example: # single request body example - name: Doe Enterprise - value: Silver + value: # needs to be declared since instance contains 'value' property + name: Doe Enterprise + value: Silver get: description: Returns an organisation entity. responses: From c0c9c5a73d4f3f4aaf2c740bdc2b8ef54be94516 Mon Sep 17 00:00:00 2001 From: krishahn Date: Thu, 21 Apr 2016 12:25:10 -0700 Subject: [PATCH 154/241] copyedit Grammar section --- versions/raml-10/raml-10.md | 12 ++++++------ 1 file changed, 6 insertions(+), 6 deletions(-) diff --git a/versions/raml-10/raml-10.md b/versions/raml-10/raml-10.md index c5c48c97..e6385e44 100644 --- a/versions/raml-10/raml-10.md +++ b/versions/raml-10/raml-10.md @@ -1073,12 +1073,12 @@ This example is actually declaring a "type alias", which gives a more readable n Type expressions are composed of names of built-in or custom types and certain symbols, as follows: -| Expression | Description | Examples -|:----------|:----------|:---------| -| | Type name (the basic building block of a type expression) | `number:` a built-in type

      `Person:` a custom type -| (type expression) | Parentheses may be used to disambiguate the expression to which an operator applies. | `Person | Animal[]`

      `( Person | Animal )[]` -| (type expression)[] | Array operator: a unary postfix operator placed after another type expression (enclosed in parentheses, as needed) and indicating that the resulting type is an array of instances of that type expression. | `string[]:` an array of strings

      `Person[][]:` an array of arrays of Person instances -| (type expression 1) | (type expression 2) | Union operator: an infix operator indicating that the resulting type may be either of type expression 1 or of type expression 2. Multiple union operators may be combined between pairs of type expressions. | `string | number:` either a string or a number

      `X | Y | Z`: either an X or a Y or a Z

      `(Manager | Admin)[]:` an array whose members consist of Manager or Admin instances

      `Manager[] | Admin[]:` an array of Manager instances or an array of Admin instances. +| Expression Components | Description | Examples +|:--------------------------|:------------|:---------| +| type name | A type name, the basic building block of a type expression, used alone creates the simplist expression. | `number:` a built-in type

      `Person:` a custom type +| (type expression) | Parentheses disambiguate the expression to which an operator applies. | `Person | Animal[]`

      `( Person | Animal )[]` +| (type expression)[] | The array, a unary, postfix operator placed after another type expression, enclosed in parentheses as needed, indicates the resulting type is an array of instances of that type expression. | `string[]:` an array of strings

      `Person[][]:` an array of arrays of Person instances +| (type expression 1) | (type expression 2) | An infix union operator indicates the resulting type might be either of type expression 1 or of type expression 2. Multiple union operators can be combined between pairs of type expressions. | `string | number:` either a string or a number

      `X | Y | Z`: either an X or a Y or a Z

      `(Manager | Admin)[]:` an array whose members consist of Manager or Admin instances

      `Manager[] | Admin[]:` an array of Manager instances or an array of Admin instances. ### Union Types From ba3ce32329096fbd2f35cb19ca19ed50e83566c0 Mon Sep 17 00:00:00 2001 From: krishahn Date: Thu, 21 Apr 2016 12:31:44 -0700 Subject: [PATCH 155/241] spelling --- versions/raml-10/raml-10.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/versions/raml-10/raml-10.md b/versions/raml-10/raml-10.md index e6385e44..dc6e4a7e 100644 --- a/versions/raml-10/raml-10.md +++ b/versions/raml-10/raml-10.md @@ -1075,7 +1075,7 @@ Type expressions are composed of names of built-in or custom types and certain s | Expression Components | Description | Examples |:--------------------------|:------------|:---------| -| type name | A type name, the basic building block of a type expression, used alone creates the simplist expression. | `number:` a built-in type

      `Person:` a custom type +| type name | A type name, the basic building block of a type expression, used alone creates the simplest expression. | `number:` a built-in type

      `Person:` a custom type | (type expression) | Parentheses disambiguate the expression to which an operator applies. | `Person | Animal[]`

      `( Person | Animal )[]` | (type expression)[] | The array, a unary, postfix operator placed after another type expression, enclosed in parentheses as needed, indicates the resulting type is an array of instances of that type expression. | `string[]:` an array of strings

      `Person[][]:` an array of arrays of Person instances | (type expression 1) | (type expression 2) | An infix union operator indicates the resulting type might be either of type expression 1 or of type expression 2. Multiple union operators can be combined between pairs of type expressions. | `string | number:` either a string or a number

      `X | Y | Z`: either an X or a Y or a Z

      `(Manager | Admin)[]:` an array whose members consist of Manager or Admin instances

      `Manager[] | Admin[]:` an array of Manager instances or an array of Admin instances. From 1cfd5113f8b70a36e93513b21ed9237001f9a416 Mon Sep 17 00:00:00 2001 From: krishahn Date: Thu, 21 Apr 2016 13:49:51 -0700 Subject: [PATCH 156/241] copyedits of Union Types section --- versions/raml-10/raml-10.md | 14 ++++++-------- 1 file changed, 6 insertions(+), 8 deletions(-) diff --git a/versions/raml-10/raml-10.md b/versions/raml-10/raml-10.md index c5c48c97..4d068963 100644 --- a/versions/raml-10/raml-10.md +++ b/versions/raml-10/raml-10.md @@ -1082,7 +1082,7 @@ Type expressions are composed of names of built-in or custom types and certain s ### Union Types -Union Types are declared using pipes (|) in your type expressions. Union Types are useful to model common scenarios in JSON based applications, for example an array containing objects which can be instances of more than one type. +Union types are declared using pipes (|) in type expressions. Union types are useful for modeling common scenarios in JSON-based applications, for example an array containing objects that can be instances of more than one type. ```yaml #%RAML 1.0 @@ -1126,7 +1126,7 @@ types: fangs: string ``` -A valid instance of the type `CatOrDog` for example looks like the following: +A following example of an instance of type `CatOrDog` is valid: ```yaml CatOrDog: # follows restrictions applied to the type 'Cat' @@ -1134,26 +1134,24 @@ CatOrDog: # follows restrictions applied to the type 'Cat' color: "brown" ``` -Imagine a more complex example where a union type is used in a multiple inheritance type expression. +Imagine a more complex example of a union type used in a multiple inheritance type expression: ```yaml types: HomeAnimal: [ HasHome , Dog | Cat ] ``` -In this case type `HomeAnimal` has two base types `HasHome` and anonymous union type defined by a type expression - `Dog | Cat` +In this case, type `HomeAnimal` has two base types, `HasHome` and an anonymous union type, defined by the following type expression: `Dog | Cat` -So testing if the `HomeAnimal` type is a valid involves taking each of its base types, and checking that a type which is derived type of this type and each of union type option types is a valid type. In this particular case you need to test that types `[HasHome, Dog]` and `[HasHome, Cat]` are valid types. +Validating the `HomeAnimal` type involves validating the types derived from each of the base types and the types of each union type option. In this particular case, you need to test that types `[HasHome, Dog]` and `[HasHome, Cat]` are valid types. -If you are extending from two union types you should do the same for every possible combination for example in this case: +If you are extending from two union types you should perform validations for every possible combination. For example, to validate the following type, you need to test six possible combinations: `[HasHome, Dog ]`, `[HasHome, Cat ]`, `[HasHome, Parrot]`, `[IsOnFarm, Dog ]`, `[IsOnFarm, Cat ]`, and `[IsOnFarm, Parrot]` ```yaml types: HomeAnimal: [ HasHome | IsOnFarm , Dog | Cat | Parrot ] ``` -In summary, you need to test 6 possible combinations: `[HasHome, Dog ]`, `[HasHome, Cat ]`, `[HasHome, Parrot]`, `[IsOnFarm, Dog ]`, `[IsOnFarm, Cat ]`, and `[IsOnFarm, Parrot]`. - ### Using XML and JSON Schema RAML allows the use of XML and JSON schema to describe the body of an API request or response, by integrating them into its data type system. From ac43908a4690967c543b6b85a5167dfab0ba759d Mon Sep 17 00:00:00 2001 From: krishahn Date: Thu, 21 Apr 2016 13:58:14 -0700 Subject: [PATCH 157/241] minor edit --- versions/raml-10/raml-10.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/versions/raml-10/raml-10.md b/versions/raml-10/raml-10.md index 4d068963..7bb86047 100644 --- a/versions/raml-10/raml-10.md +++ b/versions/raml-10/raml-10.md @@ -1145,7 +1145,7 @@ In this case, type `HomeAnimal` has two base types, `HasHome` and an anonymous u Validating the `HomeAnimal` type involves validating the types derived from each of the base types and the types of each union type option. In this particular case, you need to test that types `[HasHome, Dog]` and `[HasHome, Cat]` are valid types. -If you are extending from two union types you should perform validations for every possible combination. For example, to validate the following type, you need to test six possible combinations: `[HasHome, Dog ]`, `[HasHome, Cat ]`, `[HasHome, Parrot]`, `[IsOnFarm, Dog ]`, `[IsOnFarm, Cat ]`, and `[IsOnFarm, Parrot]` +If you are extending from two union types you should perform validations for every possible combination. For example, to validate the `HomeAnimal` type shown below, you need to test six possible combinations: `[HasHome, Dog ]`, `[HasHome, Cat ]`, `[HasHome, Parrot]`, `[IsOnFarm, Dog ]`, `[IsOnFarm, Cat ]`, and `[IsOnFarm, Parrot]`. ```yaml types: From ee92cb20d8fd7c13b847fc703256fe0bb396d9b7 Mon Sep 17 00:00:00 2001 From: krishahn Date: Thu, 21 Apr 2016 14:51:32 -0700 Subject: [PATCH 158/241] copyedit xml and json schema --- versions/raml-10/raml-10.md | 14 +++++++------- 1 file changed, 7 insertions(+), 7 deletions(-) diff --git a/versions/raml-10/raml-10.md b/versions/raml-10/raml-10.md index c5c48c97..98160328 100644 --- a/versions/raml-10/raml-10.md +++ b/versions/raml-10/raml-10.md @@ -1156,7 +1156,7 @@ In summary, you need to test 6 possible combinations: `[HasHome, Dog ]`, `[HasHo ### Using XML and JSON Schema -RAML allows the use of XML and JSON schema to describe the body of an API request or response, by integrating them into its data type system. +RAML allows the use of XML and JSON schemas to describe the body of an API request or response by integrating the schemas into its data type system. The following examples show how to include an external JSON schema into a root-level type definition and a body declaration. @@ -1175,9 +1175,9 @@ types: type: !include person.json ``` -A RAML processor MUST not allow types that define an XML or JSON schema to participate in type inheritance or specialization, or effectively in any [type expression](#type-expressions). In other words: You cannot define sub-types of these types that declare new properties, add restrictions, and set or declare facets. You can, however, create simple type wrappers that add annotations, examples or a description. +A RAML processor MUST not allow types that define an XML or JSON schema to participate in type inheritance or specialization, or effectively in any [type expression](#type-expressions). Therefore, you cannot define sub-types of these types to declare new properties, add restrictions, set facets, or declare facets. You can, however, create simple type wrappers that add annotations, examples, or a description. -The following is a fully valid example. +The following example shows a valid declaration. ```yaml types: @@ -1186,7 +1186,7 @@ types: description: this is a schema describing person ``` -However, this example shows an invalid case where a type inherits the characteristics of a JSON schema and adds additional properties. +The following example shows an invalid declaration of a type that inherits the characteristics of a JSON schema and adds additional properties. ```yaml types: @@ -1196,7 +1196,7 @@ types: single: boolean ``` -Another invalid case is the following example where the type `Person` is being used for a property type. +Another invalid case is shown in the following example of the type `Person` being used as a property type. ```yaml types: @@ -1210,9 +1210,9 @@ types: A RAML Processor MUST be able to interpret and apply JSON Schema and XML Schema. -XML schema MUST NOT be used where the media type does not allow XML-formatted data, and JSON schema MUST NOT be used where the media type does not allow JSON-formatted data. XML and JSON schemas are also forbidden in any declaration of query parameters, query string, URI parameters, and headers. +An XML schema, or JSON schema, MUST NOT be used where the media type does not allow XML-formatted data, or JSON-formatted data, respectively. XML and JSON schemas are also forbidden in any declaration of query parameters, query string, URI parameters, and headers. -Please note that the properties "schemas" and "types" are completely synonymous, so are "schema" and "type" for compatibility with RAML 0.8, but "schemas" and "schema" are deprecated. API definitions should use "types" and "type", as "schemas" and "schema" may be removed in a future RAML version. +The properties "schemas" and "types", as well as "schema" and "type", are synonymous for compatibility with RAML 0.8, but "schemas" and "schema" are deprecated. API definitions should use "types" and "type", as "schemas" and "schema" might be removed in a future RAML version. ### Multiple Inheritance From 5246096330794ae630bc04c4fc5532863b8fc34b Mon Sep 17 00:00:00 2001 From: krishahn Date: Thu, 21 Apr 2016 16:43:44 -0700 Subject: [PATCH 159/241] copyedit Inline Type Declarations and Defining Examples in RAML --- versions/raml-10/raml-10.md | 34 ++++++++++++++++++---------------- 1 file changed, 18 insertions(+), 16 deletions(-) diff --git a/versions/raml-10/raml-10.md b/versions/raml-10/raml-10.md index c5c48c97..81ebb4a8 100644 --- a/versions/raml-10/raml-10.md +++ b/versions/raml-10/raml-10.md @@ -1239,7 +1239,7 @@ If multiple parent types define a property with the same name: ### Inline Type Declarations -You can declare inline/anonymous types everywhere a type can be referenced other than in a Type Expression. +You can declare inline/anonymous types everywhere a type can be referenced except in a Type Expression. ```yaml #%RAML 1.0 @@ -1266,9 +1266,9 @@ It is highly RECOMMENDED that API documentation include a rich selection of exam #### Multiple Examples -The OPTIONAL **examples** property may be used to attach multiple examples to a type declaration. Its value is a map of key-value pairs, where each key represent a unique identifier for an example and the value is a [single example](#single-example) property. +The OPTIONAL **examples** property can be used to attach multiple examples to a type declaration. Its value is a map of key-value pairs, where each key represents a unique identifier for an example and the value is a [single example](#single-example) property. -The following is an example of the value of an **examples** property: +The following example shows the value of an **examples** property: ```yaml message: # {key} - unique id @@ -1283,9 +1283,9 @@ record: # {key} - unique id #### Single Example -The OPTIONAL **example** property may be used to attach an example of a type's instance to the type declaration. There are two different ways to represents its value. +The OPTIONAL **example** property can be used to attach an example of a type instance to the type declaration. There are two ways to represent the example property value: as an explicit description of a specific type instance and as a map that contains additional facets. -##### The value is a explicit description of a specific type instance +##### As an explicit description of a specific type instance For example: @@ -1294,15 +1294,17 @@ title: Attention needed body: You have been added to group 274 ``` -##### The value is a map that contains the following additional facets +##### As a map that contains additional facets + +The map can contain the following additional facets: | Facet | Description | |:--------|:------------| | displayName? | An alternate, human-friendly name for the example. If the example is part of an examples node, the default value is the unique identifier that is defined for this example. | description? | A longer, human-friendly description of the example. -| (<annotationName>)? | Annotations to be applied to this example. Annotations are any property whose key begins with "(" and ends with ")" and whose name (the part between the beginning and ending parentheses) is a declared annotation name. See section [Annotations](#annotations) for more information. +| (<annotationName>)? | [Annotations](#annotations) to be applied to this example. An annotation is a property having a key that begins with "(" and ends with ")". The text enclosed in parentheses is the annotation name. | value | The actual example of a type instance. -| strict? | By default, an example is validated against any type declaration. Set this to false avoid that. +| strict? | Validates the example against any type declaration (the default), or not. Set this to false avoid validation. For example: @@ -1314,9 +1316,9 @@ value: body: You have been added to group 274 ``` -#### Example on how to define example/examples in RAML +#### Example of how to define example/examples in RAML -The following illustrates usage of both example and examples properties at different levels of a RAML API. +The following snippet illustrates the usage of example and examples properties at different levels of a RAML API: ```yaml #%RAML 1.0 @@ -1336,23 +1338,23 @@ types: properties: name: string address?: string - value? : string -/organisation: + value?: string +/organization: post: headers: UserID: - description: the identifier for the user that posts a new organisation + description: the identifier for the user who posts a new organization type: string example: SWED-123 # single scalar example body: application/json: type: Org example: # single request body example - value: # needs to be declared since instance contains 'value' property + value: # needs to be declared since instance contains a 'value' property name: Doe Enterprise value: Silver get: - description: Returns an organisation entity. + description: Returns an organization entity. responses: 201: body: @@ -1365,7 +1367,7 @@ types: value: # validate against the available facets for the map value of an example name: Software Corp address: 35 Central Street - value: Gold # validate against instance of the `value` property + value: Gold # validate against an instance of the `value` property ``` ### XML Serialization of Type Instances From 4bfcb6b7f51a06864450f5d93547bc9db8d23ed1 Mon Sep 17 00:00:00 2001 From: krishahn Date: Thu, 21 Apr 2016 17:40:13 -0700 Subject: [PATCH 160/241] copyedit XML Serialization of Type Instances --- versions/raml-10/raml-10.md | 18 +++++++++--------- 1 file changed, 9 insertions(+), 9 deletions(-) diff --git a/versions/raml-10/raml-10.md b/versions/raml-10/raml-10.md index c5c48c97..c37b2e5d 100644 --- a/versions/raml-10/raml-10.md +++ b/versions/raml-10/raml-10.md @@ -1370,17 +1370,17 @@ types: ### XML Serialization of Type Instances -As the serialization to XML may be a complex process, RAML introduces an additional `xml` node for [type declarations](#type-declarations) that allows to configure how type instances should be serialized to XML. The value of the `xml` node is a map that contains the following nodes. +To facilitate the potentially complex process of serialization to XML, RAML introduces an additional `xml` node for [type declarations](#type-declarations). This node is used to configure how type instances should be serialized to XML. The value of the `xml` node is a map that contains the following nodes: | Name | Type | Description | |:---------|:------:|:-----------------| -| attribute? | `boolean` | If `attribute` is set to `true`, a type instance should be serialized as an XML attribute. It can only be `true` for scalar types.

      **Default:** `false` -| wrapped? | `boolean` | If `wrapped` is set to `true`, a type instance should be wrapped in its own XML element. It can not be `true` for scalar types and it can not be `true` at the same moment when `attribute` is `true`.

      **Default:** `false` -| name? | `string` | Allows to override the name of the XML element or XML attribute in it's XML representation.

      **Default:** the name of the type -| namespace? | `string` | Allows to configure the name of the XML namespace. -| prefix? | `string` | Allows to configure the prefix which will be used during serialization to XML. +| attribute? | `boolean` | `true` serializes a type instance as an XML attribute. Can be `true` only for scalar types.

      **Default:** `false` +| wrapped? | `boolean` | `true` wraps a type instance in its own XML element. Cannot be `true` for scalar types or `true` at the same moment `attribute` is `true`.

      **Default:** `false` +| name? | `string` | Overrides the name of the XML element or XML attribute.

      **Default:** the name of the type +| namespace? | `string` | Configures the name of the XML namespace. +| prefix? | `string` | Configures the prefix used during serialization to XML. -The following is a type declaration example that uses the `xml` node: +The following type declaration shows an example of using the `xml` node: ```yaml types: @@ -1394,14 +1394,14 @@ types: addresses: type: Address[] xml: - wrapped: true # serialize it into it's own ... XML element + wrapped: true # serialize it into its own ... XML element Address: properties: street: string city: string ``` -The example above may be serialized into the following XML: +The example above can be serialized into the following XML: ```xml From a2f215ce3ac4f8b67d21ed9b4e510414706a69e8 Mon Sep 17 00:00:00 2001 From: krishahn Date: Thu, 21 Apr 2016 20:53:08 -0700 Subject: [PATCH 161/241] copyedit Using Types in Raml --- versions/raml-10/raml-10.md | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/versions/raml-10/raml-10.md b/versions/raml-10/raml-10.md index c5c48c97..b430a181 100644 --- a/versions/raml-10/raml-10.md +++ b/versions/raml-10/raml-10.md @@ -1414,16 +1414,16 @@ The example above may be serialized into the following XML: ### Using Types in RAML -* Types may be used in several positions: +* Types can be used in several positions: * Body ( JSON ) * Body ( XML ) * Body ( Web Form ) * Headers * Query Parameters * URI Parameters -* Serialization rules depend on both the type and the position in which it is used -* When declaring a custom value type ( extending the "value" built-in type ) it will have "string" as its default serialization target. -* When extending one of the built-in types, your type will inherit the serialization target +* Serialization rules depend on the type and the position in which the type is used. +* A "string" is the default serialization target of a custom value type, which is an extended "value" of a built-in type. +* An extended built-in type inherits its serialization target. ## Resources and Nested Resources From a203525ae274b8e66b03d1dab7a3b42c12f34f0a Mon Sep 17 00:00:00 2001 From: krishahn Date: Thu, 21 Apr 2016 21:02:29 -0700 Subject: [PATCH 162/241] formatting --- versions/raml-10/raml-10.md | 5 ++++- 1 file changed, 4 insertions(+), 1 deletion(-) diff --git a/versions/raml-10/raml-10.md b/versions/raml-10/raml-10.md index b430a181..3435e377 100644 --- a/versions/raml-10/raml-10.md +++ b/versions/raml-10/raml-10.md @@ -1414,13 +1414,16 @@ The example above may be serialized into the following XML: ### Using Types in RAML -* Types can be used in several positions: +Types can be used in several positions: * Body ( JSON ) * Body ( XML ) * Body ( Web Form ) * Headers * Query Parameters * URI Parameters + +Key points about serialization are: + * Serialization rules depend on the type and the position in which the type is used. * A "string" is the default serialization target of a custom value type, which is an extended "value" of a built-in type. * An extended built-in type inherits its serialization target. From 2daa94ae13012924e737933ea429ab0148f540e4 Mon Sep 17 00:00:00 2001 From: krishahn Date: Fri, 22 Apr 2016 07:22:24 -0700 Subject: [PATCH 163/241] copyedit Resources and Nested Resources --- versions/raml-10/raml-10.md | 14 +++++++------- 1 file changed, 7 insertions(+), 7 deletions(-) diff --git a/versions/raml-10/raml-10.md b/versions/raml-10/raml-10.md index c5c48c97..b1ea4cd9 100644 --- a/versions/raml-10/raml-10.md +++ b/versions/raml-10/raml-10.md @@ -1427,9 +1427,9 @@ The example above may be serialized into the following XML: ## Resources and Nested Resources -Resources are identified by their relative URI, which MUST begin with a slash ("/"). Every property whose key begins with a slash, and is either at the root of the API definition or is the child property of a resource property, is such a resource property. +A resource is identified by its relative URI, which MUST begin with a slash ("/"). Every property whose key begins with a slash, and is either at the root of the API definition or is the child property of a resource property, is such a resource property. -A resource defined as a root-level property is called a top-level resource. Its property's key is the resource's URI relative to the baseUri (if any). A resource defined as a child property of another resource is called a nested resource, and its property's key is its URI relative to its parent resource's URI. +A resource defined as a root-level property is called a top-level resource. The key of the root-level property is the URI of the resource relative to the baseUri if there is one. A resource defined as a child property of another resource is called a nested resource. The key of the child property is the URI of the nested resource relative to the parent resource URI. This example shows an API definition with one top-level resource, /gists, and one nested resource, /public. @@ -1444,11 +1444,11 @@ baseUri: https://api.github.com displayName: Public Gists ``` -The key of a resource property, i.e. its relative URI, MAY consist of multiple URI path fragments separated by slashes; e.g. /bom/items may indicate the collection of items in a bill of materials as a single resource. However, if the individual URI path fragments are themselves resources, the API definition SHOULD use nested resources to describe this structure; e.g. if /bom is itself a resource then /items should be a nested resource of /bom, vs using /bom/items as a non-nested resource. +The key of a resource property, its relative URI, MAY consist of multiple URI path fragments separated by slashes. For example, /bom/items might indicate the collection of items in a bill of materials as a single resource. However, if the individual URI path fragments are themselves resources, the API definition SHOULD use nested resources to describe this structure. For example, if /bom is itself a resource, then /items should be a nested resource of /bom, versus using /bom/items as a non-nested resource. Absolute URIs are not explicitly specified. They are computed by appending the relative URI of the top-level resource, and then successively appending the relative URI values for each nested resource until the target resource is reached. In this formation of the absolute URI, if a baseUri is defined, it is prepended before the relative URI of the top-level resource; any trailing slashes in the baseUri are removed before prepending. -Taking the previous example, the absolute URI of the public gists resource is formed as follows. +Continuing with the previous example, the absolute URI of the public gists resource is formed as follows. ``` "https://api.github.com" <--- baseUri @@ -1495,9 +1495,9 @@ https://api.github.com/users/{userId}/keys https://api.github.com/users/{userId}/keys/{keyId} ``` -A RAML processor MUST NOT allow one of the computed absolute URIs to be identical to another one; comparison of absolute URIs is done without consideration to the possible values of any URI parameter, i.e. any URI parameters are not expanded or evaluated but rather left as is. +A RAML processor MUST NOT allow one of the computed absolute URIs to be identical to another one; comparison of absolute URIs is done without consideration to the possible values of any URI parameter. Any URI parameter is not expanded or evaluated, but rather left as is. -The following example would be forbidden. +The following example shows effectively duplicated URIs, as both paths combine to the same `/users/foo`. This is forbidden. ```yaml /users: @@ -1505,7 +1505,7 @@ The following example would be forbidden. /users/foo: ``` -(both paths combine to the same `/users/foo`), and on the other hand this would ALWAYS be ALLOWED. +The URIs in the following example would ALWAYS be ALLOWED. ```yaml /users/{userId}: From 33a68e0b4d7bed45c1941d098a75b76130b2e99a Mon Sep 17 00:00:00 2001 From: krishahn Date: Fri, 22 Apr 2016 07:50:14 -0700 Subject: [PATCH 164/241] minor edit for consistency --- versions/raml-10/raml-10.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/versions/raml-10/raml-10.md b/versions/raml-10/raml-10.md index 637b5603..ab5b9ae9 100644 --- a/versions/raml-10/raml-10.md +++ b/versions/raml-10/raml-10.md @@ -1500,7 +1500,7 @@ https://api.github.com/users/{userId}/keys/{keyId} A RAML processor MUST NOT allow one of the computed absolute URIs to be identical to another one; comparison of absolute URIs is done without consideration to the possible values of any URI parameter. Any URI parameter is not expanded or evaluated, but rather left as is. -The following example shows effectively duplicated URIs, as both paths combine to the same `/users/foo`. This is forbidden. +The following example shows effectively duplicated URIs, as both paths combine to the same `/users/foo`. This would be forbidden. ```yaml /users: From 461d2dc9e76d0ef37f6a1a4533bea89d68098b54 Mon Sep 17 00:00:00 2001 From: krishahn Date: Fri, 22 Apr 2016 09:30:52 -0700 Subject: [PATCH 165/241] add that schemas and types are mutually exclusive --- versions/raml-10/raml-10.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/versions/raml-10/raml-10.md b/versions/raml-10/raml-10.md index 98160328..83f78ce9 100644 --- a/versions/raml-10/raml-10.md +++ b/versions/raml-10/raml-10.md @@ -1212,7 +1212,7 @@ A RAML Processor MUST be able to interpret and apply JSON Schema and XML Schema. An XML schema, or JSON schema, MUST NOT be used where the media type does not allow XML-formatted data, or JSON-formatted data, respectively. XML and JSON schemas are also forbidden in any declaration of query parameters, query string, URI parameters, and headers. -The properties "schemas" and "types", as well as "schema" and "type", are synonymous for compatibility with RAML 0.8, but "schemas" and "schema" are deprecated. API definitions should use "types" and "type", as "schemas" and "schema" might be removed in a future RAML version. +The properties "schemas" and "types", as well as "schema" and "type", are mutually exclusive and synonymous for compatibility with RAML 0.8. API definitions should use "types" and "type", as "schemas" and "schema" are deprecated and might be removed in a future RAML version. ### Multiple Inheritance From 66e6252caff85e64ade762ec12ace8fe5ef66c6f Mon Sep 17 00:00:00 2001 From: Christian Vogel Date: Fri, 22 Apr 2016 17:32:57 +0100 Subject: [PATCH 166/241] fixed bug inside an example for traits --- versions/raml-10/raml-10.md | 1 + 1 file changed, 1 insertion(+) diff --git a/versions/raml-10/raml-10.md b/versions/raml-10/raml-10.md index c5c48c97..95b44e44 100644 --- a/versions/raml-10/raml-10.md +++ b/versions/raml-10/raml-10.md @@ -2267,6 +2267,7 @@ traits: - mac /installer: get: + is: [ withQueryParameters ] queryParameters: platform: #the actual enum is [ mac, unix, win ] enum: From 84d417dfccf620cb3361369cc80b0735e23b37a8 Mon Sep 17 00:00:00 2001 From: krishahn Date: Fri, 22 Apr 2016 23:14:21 -0700 Subject: [PATCH 167/241] copyedit Resource Property thru Template URIs --- versions/raml-10/raml-10.md | 40 ++++++++++++++++++------------------- 1 file changed, 20 insertions(+), 20 deletions(-) diff --git a/versions/raml-10/raml-10.md b/versions/raml-10/raml-10.md index b1beede9..eeffc7c2 100644 --- a/versions/raml-10/raml-10.md +++ b/versions/raml-10/raml-10.md @@ -1524,17 +1524,17 @@ The value of a resource property is an object whose properties are described in |:--------|:------------| | displayName? | An alternate, human-friendly name for the resource. | description? | A longer, human-friendly description of the resource. -| (<annotationName>)? | Annotations to be applied to this resource. Annotations are any property whose key begins with "(" and ends with ")" and whose name (the part between the beginning and ending parentheses) is a declared annotation name. See section [Annotations](#annotations). -| get?
      patch?
      put?
      post?
      delete?
      options?
      head? | Object describing the method. See section [Methods](#methods) for more information. -| is? | A list of the traits to apply to all methods declared (implicitly or explicitly) for this resource. See section [Applying Resource Types and Traits](#applying-resource-types-and-traits) for more information. Individual methods may override this declaration -| type? | The resource type which this resource inherits. See section [Applying Resource Types and Traits](#applying-resource-types-and-traits) for more information. -| securedBy? | The security schemes that apply to all methods declared (implicitly or explicitly) for this resource. See section [Applying Security Schemes](#applying-security-schemes) for more information. -| uriParameters? | Detailed information about any URI parameters of this resource -| /<relativeUri>? | A nested resource is identified as any property whose name begins with a slash ("/") and is therefore treated as a relative URI. +| (<annotationName>)? | [Annotations](#annotations) to be applied to this resource. An annotation is a property having a key that begins with "(" and ends with ")". The text enclosed in parentheses is the annotation name. +| get?
      patch?
      put?
      post?
      delete?
      options?
      head? | The object describing the [method](#methods). +| is? | A list of [traits to apply](#applying-resource-types-and-traits) to all methods declared (implicitly or explicitly) for this resource. Individual methods can override this declaration. +| type? | The [resource type](#applying-resource-types-and-traits) that this resource inherits. +| securedBy? | The [security schemes](#applying-security-schemes) that apply to all methods declared (implicitly or explicitly) for this resource. +| uriParameters? | Detailed information about any URI parameters of this resource. +| /<relativeUri>? | A nested resource, which is identified as any property whose name begins with a slash ("/"), and is therefore treated as a relative URI. ### Resource Display Name -The OPTIONAL **displayName** property provides a friendly name to the resource and can be used by documentation generation tools. If the displayName property is not defined for a resource, documentation tools SHOULD refer to the resource by its property key (i.e. its relative URI, e.g., /jobs), which acts as the resource's name. +The OPTIONAL **displayName** property assigns a friendly name to the resource and can be used by documentation generation tools. If the displayName property is not defined for a resource, documentation tools SHOULD refer to the resource by its property key, which acts as the resource name. For example, tools should refer to the relative URI /jobs. ### Resource Description @@ -1542,7 +1542,7 @@ The OPTIONAL **description** property can be used to provide a longer descriptio ### Template URIs and URI Parameters -[Template URIs](#template-uri) containing URI parameters can be used to define a resource's relative URI when it contains variable elements. The following example shows a top-level resource with a key /jobs and a nested resource with a key /{jobId}. +[Template URIs](#template-uri) containing URI parameters can be used to define a relative URI of a resource that contains variable elements. The following example shows a top-level resource with a key /jobs and a nested resource with a key /{jobId}, a template URI. ```yaml #%RAML 1.0 @@ -1555,13 +1555,13 @@ baseUri: https://app.zencoder.com/api/{version} description: A specific job, a member of the jobs collection ``` -The OPTIONAL **uriParameters** property is used to explicitly specify URI parameters in a [Template URI](#template-uri). The value of the uriParameters property is an object, specifically a [properties declaration](#property-declarations), as is the value of the properties object of a type declaration. Each property in this declaration object is referred to as a **URI parameter declaration**. The name of each such property corresponds to the name of a parameter in the [Template URI](#template-uri), while its value specifies the URI parameter's type, as the name of a type or an inline type declaration. +The OPTIONAL **uriParameters** property, shown in the next example, is used to explicitly specify URI parameters in a [Template URI](#template-uri). The value of the uriParameters property is an object, specifically a [properties declaration](#property-declarations), as is the value of the properties object of a type declaration. Each property in the declaration object is a **URI parameter declaration**. Each property name corresponds to a parameter name in the [Template URI](#template-uri). Each value specifies the URI parameter type as a type name or an inline type declaration. -Every property in a uriParameters declaration MUST correspond exactly to the name of a URI parameter in the resource's relative URI. But not every URI parameter in the resource's relative URI must be explicitly specified in the uriParameters property. Every parameter in the relative URI not specified in the uriParameters property MUST still be treated as a URI parameter, of type string, and required. +Every property in a uriParameters declaration MUST correspond exactly to the name of a URI parameter in the relative URI of the resource. All URI parameters in the relative URI do not need to be explicitly specified in the uriParameters property, but those that are not specified MUST be treated as a URI parameter of type string and required. -Just as is the case for [the baseUriParameters root property](#base-uri-and-base-uri-parameters), the version parameter is a reserved parameter name in the uriParameters properties declaration, with a value corresponding to the value of the version root-level property. +Like the [baseUriParameters root property](#base-uri-and-base-uri-parameters), the version parameter is a reserved parameter name in the uriParameters properties declaration. The version parameter value corresponds to the value of the version root-level property. -The example below shows two top-level resources (/user and /users) and a nested resource specified by its [Template URI](#template-uri), /{userId}. The URI parameter userId is explicitly declared, and given a description and an integer type. +The following example shows two top-level resources, /user and /users, and a nested resource specified by its [Template URI](#template-uri), /{userId}. The URI parameter, userId, is explicitly declared and given a description and an integer type. ```yaml #%RAML 1.0 @@ -1580,7 +1580,7 @@ baseUri: https://api.github.com type: integer ``` -If a URI parameter declaration specifies an array, object, or union of non-scalar types, then processors MUST default to treating the format of the URI parameter value as JSON in applying the type to instances of that URI parameter. The following demonstrates an extreme example of the expected behavior. +If a URI parameter declaration specifies an array, object, or union of non-scalar types, then processors MUST default to applying the JSON type to values of URI parameter instances. The following example exaggerates the expected behavior: ```yaml #%RAML 1.0 @@ -1600,13 +1600,13 @@ title: Serialization API uniqueItems: true ``` -In the example above, the URI parameter `userIds` is an array of ids. Let us assume the array should contain `[blue,green]` which then, on the wire may look as: `/users/%5B%22blue%22,%22green%22%5D/`. +In this example, the URI parameter `userIds` is an array of ids. Assume the array should contain `[blue,green]`, which on the wire might appear as `/users/%5B%22blue%22,%22green%22%5D/`. If a URI parameter declaration specifies a non-string scalar type for the value of the header, the standard serialization rules for types MUST be invoked in applying the type to instances of that URI parameter. -The values matched by URI parameters MUST NOT contain slash (/) characters, in order to avoid ambiguous matching. In the example above, a URI (relative to the baseUri) of /jobs/123 matches the /{jobId} resource nested within the /jobs resource, but a URI of /jobs/123/x does not match any of those resources. +The values matched by URI parameters MUST NOT contain slash (/) characters in order to avoid ambiguous matching. In the first example in this section, a URI (relative to the baseUri) of /jobs/123 matches the /{jobId} resource nested within the /jobs resource, but a URI of /jobs/123/x does not match any of those resources. -In the example below, the top-level resource has two URI parameters, folderId and fileId. +In the next example, the top-level resource has two URI parameters, folderId and fileId. ```yaml #%RAML 1.0 @@ -1618,15 +1618,15 @@ version: v1 description: An item in the collection of all files ``` -Although URI parameters can be explicitly specified to be optional, they SHOULD be required when they are surrounded directly by slashes ("/"), that is, when they constitute complete URI path fragments, e.g. .../{objectId}/.... It usually makes little sense to allow a URI to contain adjacent slashes with no characters between them, e.g. ...//.... Hence, a URI parameter should only be specified as optional when it appears adjacent to other text; e.g., /people/~{fieldSelectors} indicates that the {fieldSelectors} URI parameter can be blank, and therefore optional, indicating that /people/~ is a valid relative URI. +Although a URI parameter can be explicitly specified as optional, it SHOULD be required when surrounded directly by slashes ("/"). In this case, the URI parameter constitutes a complete URI path fragment, for example .../{objectId}/.... It usually makes little sense to allow a URI to contain adjacent slashes, enclosing no characters, for example ...//.... Hence, a URI parameter should be specified as optional only when it appears adjacent to other text. For example, /people/~{fieldSelectors} indicates that the {fieldSelectors} URI parameter can be blank, and therefore optional, implying that /people/~ is a valid relative URI. -A special URI parameter, **ext**, is a reserved parameter. It may or may not be specified explicitly in a uriParameters property, but its meaning is reserved: it is used by a client to specify that the body of the request or response be of the associated media type. +A special URI parameter, **ext**, is a reserved parameter. This parameter might or might not be specified explicitly in a uriParameters property, but its meaning is reserved: it is used by a client to specify that the body of the request or response be of the associated media type. |URI Parameter | Value | |:--------|:------------| | ext | The desired media type of the request or response body -By convention, a value for the ext parameter of .json is equivalent to an Accept header of application/json, and a value of .xml is equivalent to an Accept header of text/xml. By employing the ext parameter, clients may specify the media type of a request or response via the URI rather than via the Accept HTTP header. For example, in the following example, the /users resource may be requested as application/json or text/xml: +By convention, a value for the ext parameter of .json is equivalent to an Accept header of application/json. A value of .xml is equivalent to an Accept header of text/xml. By employing the ext parameter, clients can specify the media type of a request or response through the URI rather than the Accept HTTP header. In the following example, the /users resource can be requested as application/json or text/xml: ```yaml #%RAML 1.0 From 45a1816c11466260bdd3a1d665458552db4e6e2f Mon Sep 17 00:00:00 2001 From: krishahn Date: Sat, 23 Apr 2016 10:18:56 -0700 Subject: [PATCH 168/241] copyedits of Methods, Method-level Display Name, and Method-level description --- versions/raml-10/raml-10.md | 20 ++++++++++---------- 1 file changed, 10 insertions(+), 10 deletions(-) diff --git a/versions/raml-10/raml-10.md b/versions/raml-10/raml-10.md index b1beede9..0bb5a2ed 100644 --- a/versions/raml-10/raml-10.md +++ b/versions/raml-10/raml-10.md @@ -1641,25 +1641,25 @@ version: v1 ## Methods -In a RESTful API, methods are operations that are performed on a resource. The OPTIONAL properties **get**, **patch**, **put**, **post**, **delete**, **head**, and **options** of a resource define its methods; these correspond to the HTTP methods defined in the HTTP version 1.1 specification [RFC2616](https://www.ietf.org/rfc/rfc2616.txt) and its extension, [RFC5789](https://tools.ietf.org/html/rfc5789). The value of any of these method properties is an object whose properties are described in the following table. +RESTful API methods are operations that are performed on a resource. The OPTIONAL properties **get**, **patch**, **put**, **post**, **delete**, **head**, and **options** of a resource define its methods; these correspond to the HTTP methods defined in the HTTP version 1.1 specification [RFC2616](https://www.ietf.org/rfc/rfc2616.txt) and its extension, [RFC5789](https://tools.ietf.org/html/rfc5789). The value of these method properties is an object that has the following properties: |Property | Description | |:--------|:------------| -| displayName? | An alternate, human-friendly name for the method (in the resource's context). -| description? | A longer, human-friendly description of the method (in the resource's context). -| (<annotationName>)? | Annotations to be applied to this method. Annotations are any property whose key begins with "(" and ends with ")" and whose name (the part between the beginning and ending parentheses) is a declared annotation name. See section [Annotations](#annotations) for more information. +| displayName? | An alternate, human-friendly method name in the context of the resource. +| description? | A longer, human-friendly description of the method in the context of the resource. +| (<annotationName>)? | [Annotations](#annotations) to be applied to this method. An annotation is a property having a key that begins with "(" and ends with ")". The text enclosed in parentheses is the annotation name. | queryParameters? | Detailed information about any query parameters needed by this method. Mutually exclusive with queryString. | headers? | Detailed information about any request headers needed by this method. -| queryString? | Specifies the query string needed by this method. Mutually exclusive with queryParameters. +| queryString? | The query string needed by this method. Mutually exclusive with queryParameters. | responses? | Information about the expected responses to a request. -| body? | Some methods admit request bodies, which are described by this property. -| protocols? | A method can override the protocols specified in the resource or at the API root, by employing this property. See section [Method-level Protocols](#method-level-protocols) for more information. -| is? | A list of the traits to apply to this method. See [Applying Resource Types and Traits](#applying-resource-types-and-traits) section. -| securedBy? | The security schemes that apply to this method. See section [Applying Security Schemes](#applying-security-schemes) for more information. +| body? | Request bodies that methods admit. +| protocols? | A method that overrides the [protocols](#method-level-protocols) specified in the resource or at the API root. +| is? | A list of the [traits](#applying-resource-types-and-traits) to apply to this method. +| securedBy? | The [security schemes](#applying-security-schemes) that apply to this method. ### Method-level Display Name -The OPTIONAL **displayName** property provides a friendly name for the method and can be used by documentation generation tools. If the displayName property is not defined for a method, documentation tools SHOULD refer to the resource by its property key, which acts as the method's name. +The OPTIONAL **displayName** property provides a friendly name for the method and can be used by documentation generation tools. If the displayName property is not defined for a method, documentation tools SHOULD refer to the resource by its property key, which acts as the method name. ### Method-level Description From 483dfb866dd106ee820653769016cb9deab4c37d Mon Sep 17 00:00:00 2001 From: krishahn Date: Sat, 23 Apr 2016 10:34:42 -0700 Subject: [PATCH 169/241] corrections to edits --- versions/raml-10/raml-10.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/versions/raml-10/raml-10.md b/versions/raml-10/raml-10.md index 0bb5a2ed..db1ce908 100644 --- a/versions/raml-10/raml-10.md +++ b/versions/raml-10/raml-10.md @@ -1652,8 +1652,8 @@ RESTful API methods are operations that are performed on a resource. The OPTIONA | headers? | Detailed information about any request headers needed by this method. | queryString? | The query string needed by this method. Mutually exclusive with queryParameters. | responses? | Information about the expected responses to a request. -| body? | Request bodies that methods admit. -| protocols? | A method that overrides the [protocols](#method-level-protocols) specified in the resource or at the API root. +| body? | A request body that the method admits. +| protocols? | The [protocols](#method-level-protocols) that override those specified in the resource or at the API root. | is? | A list of the [traits](#applying-resource-types-and-traits) to apply to this method. | securedBy? | The [security schemes](#applying-security-schemes) that apply to this method. From 4c554ccd327faab2792dcfbd8acc72c61aedf2a3 Mon Sep 17 00:00:00 2001 From: krishahn Date: Sat, 23 Apr 2016 11:17:42 -0700 Subject: [PATCH 170/241] tweaks to previous edits --- versions/raml-10/raml-10.md | 10 +++++----- 1 file changed, 5 insertions(+), 5 deletions(-) diff --git a/versions/raml-10/raml-10.md b/versions/raml-10/raml-10.md index eeffc7c2..1c7b43d2 100644 --- a/versions/raml-10/raml-10.md +++ b/versions/raml-10/raml-10.md @@ -1555,7 +1555,7 @@ baseUri: https://app.zencoder.com/api/{version} description: A specific job, a member of the jobs collection ``` -The OPTIONAL **uriParameters** property, shown in the next example, is used to explicitly specify URI parameters in a [Template URI](#template-uri). The value of the uriParameters property is an object, specifically a [properties declaration](#property-declarations), as is the value of the properties object of a type declaration. Each property in the declaration object is a **URI parameter declaration**. Each property name corresponds to a parameter name in the [Template URI](#template-uri). Each value specifies the URI parameter type as a type name or an inline type declaration. +The OPTIONAL **uriParameters** property, shown in the next example, is used to explicitly specify URI parameters in a [Template URI](#template-uri). The value of the uriParameters property is an object, specifically a [properties declaration](#property-declarations), as is the value of the properties object of a type declaration. Each property in the declaration object is a **URI parameter declaration**. Each property name corresponds to a parameter name in the [Template URI](#template-uri). Each property value specifies the URI parameter type as a type name or an inline type declaration. Every property in a uriParameters declaration MUST correspond exactly to the name of a URI parameter in the relative URI of the resource. All URI parameters in the relative URI do not need to be explicitly specified in the uriParameters property, but those that are not specified MUST be treated as a URI parameter of type string and required. @@ -1604,9 +1604,9 @@ In this example, the URI parameter `userIds` is an array of ids. Assume the arra If a URI parameter declaration specifies a non-string scalar type for the value of the header, the standard serialization rules for types MUST be invoked in applying the type to instances of that URI parameter. -The values matched by URI parameters MUST NOT contain slash (/) characters in order to avoid ambiguous matching. In the first example in this section, a URI (relative to the baseUri) of /jobs/123 matches the /{jobId} resource nested within the /jobs resource, but a URI of /jobs/123/x does not match any of those resources. +The values matched by URI parameters MUST NOT contain slash (/) characters in order to avoid ambiguous matching. In the first example in this section, /jobs/123 is a URI (relative to the baseUri) that matches the /{jobId} resource nested within the /jobs resource, but the URI /jobs/123/x does not match any resource. -In the next example, the top-level resource has two URI parameters, folderId and fileId. +In the next example, the top-level resource has URI parameters folderId and fileId. ```yaml #%RAML 1.0 @@ -1618,9 +1618,9 @@ version: v1 description: An item in the collection of all files ``` -Although a URI parameter can be explicitly specified as optional, it SHOULD be required when surrounded directly by slashes ("/"). In this case, the URI parameter constitutes a complete URI path fragment, for example .../{objectId}/.... It usually makes little sense to allow a URI to contain adjacent slashes, enclosing no characters, for example ...//.... Hence, a URI parameter should be specified as optional only when it appears adjacent to other text. For example, /people/~{fieldSelectors} indicates that the {fieldSelectors} URI parameter can be blank, and therefore optional, implying that /people/~ is a valid relative URI. +Although a URI parameter can be explicitly specified as optional, it SHOULD be required when surrounded directly by slashes ("/"). In this case, the URI parameter constitutes a complete URI path fragment, for example .../{objectId}/.... It usually makes no sense to allow a URI to contain adjacent slashes, enclosing no characters, for example ...//.... Hence, a URI parameter should be specified as optional only when it appears adjacent to other text. For example, /people/~{fieldSelectors} indicates that URI parameter {fieldSelectors} can be blank, and therefore optional, implying that /people/~ is a valid relative URI. -A special URI parameter, **ext**, is a reserved parameter. This parameter might or might not be specified explicitly in a uriParameters property, but its meaning is reserved: it is used by a client to specify that the body of the request or response be of the associated media type. +A special URI reserved parameter, **ext**, might or might not be specified explicitly in a uriParameters property. Its meaning is reserved for use by a client to specify that the body of the request or response be of the associated media type. |URI Parameter | Value | |:--------|:------------| From 00eee6bf0dfbedc849c85f5bf500cc69e3225408 Mon Sep 17 00:00:00 2001 From: krishahn Date: Sat, 23 Apr 2016 11:29:45 -0700 Subject: [PATCH 171/241] minor edits --- versions/raml-10/raml-10.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/versions/raml-10/raml-10.md b/versions/raml-10/raml-10.md index 1c7b43d2..b7728dab 100644 --- a/versions/raml-10/raml-10.md +++ b/versions/raml-10/raml-10.md @@ -1580,7 +1580,7 @@ baseUri: https://api.github.com type: integer ``` -If a URI parameter declaration specifies an array, object, or union of non-scalar types, then processors MUST default to applying the JSON type to values of URI parameter instances. The following example exaggerates the expected behavior: +If a URI parameter declaration specifies an array, object, or union of non-scalar types, then processors MUST default to applying the JSON type to values of the URI parameter instances. The following example exaggerates the expected behavior: ```yaml #%RAML 1.0 @@ -1604,7 +1604,7 @@ In this example, the URI parameter `userIds` is an array of ids. Assume the arra If a URI parameter declaration specifies a non-string scalar type for the value of the header, the standard serialization rules for types MUST be invoked in applying the type to instances of that URI parameter. -The values matched by URI parameters MUST NOT contain slash (/) characters in order to avoid ambiguous matching. In the first example in this section, /jobs/123 is a URI (relative to the baseUri) that matches the /{jobId} resource nested within the /jobs resource, but the URI /jobs/123/x does not match any resource. +To avoid ambiguous matching, the values matched by URI parameters MUST NOT contain slash (/) characters. In the first example in this section, /jobs/123 is a URI (relative to the baseUri) that matches the /{jobId} resource nested within the /jobs resource, but the URI /jobs/123/x does not match any resource. In the next example, the top-level resource has URI parameters folderId and fileId. From 8a182c9886ffb762b742049c4994ac8c1d193fef Mon Sep 17 00:00:00 2001 From: krishahn Date: Sat, 23 Apr 2016 20:26:42 -0700 Subject: [PATCH 172/241] copyedit Headers section --- versions/raml-10/raml-10.md | 14 +++++++------- 1 file changed, 7 insertions(+), 7 deletions(-) diff --git a/versions/raml-10/raml-10.md b/versions/raml-10/raml-10.md index b1beede9..418d75cf 100644 --- a/versions/raml-10/raml-10.md +++ b/versions/raml-10/raml-10.md @@ -1681,7 +1681,7 @@ baseUri: https://app.zencoder.com/api/{version} ### Headers -An API's methods may support or require various HTTP headers. The OPTIONAL **headers** property is used to explicitly specify those headers. The value of the headers property is an object, specifically a [properties declaration](#property-declarations), as is the value of the properties object of a type declaration. Each property in this declaration object is referred to as a header **declaration**. The name of each such property specifies an allowed header name, while its value specifies the header value's type, as the name of a type or an inline type declaration. +An API's methods can support or require various HTTP headers. The OPTIONAL **headers** property is used to explicitly specify those headers. The value of the headers property is an object, specifically a [properties declaration](#property-declarations), as is the value of the properties object of a type declaration. Each property in this declaration object is a header **declaration**. Each property name specifies an allowed header name. Each property value specifies the header value type as a type name or an inline type declaration. The following simple example shows a post method with a single HTTP header named Zencoder-Api-Key of (implied) string type. @@ -1698,15 +1698,15 @@ baseUri: https://app.zencoder.com/api/{version} description: The API key needed to create a new job ``` -If a header declaration specifies an array type for the value of the header, processors MUST interpret this as allowing multiple instances of that header in the request or response, as appropriate. In such a case, the underlying type of the array -- namely, the type of the elements of the array -- MUST be applied as the type of the value of instances of this header. +If a header declaration specifies an array type for the value of the header, processors MUST allow multiple instances of that header in the request or response. In this case, the type of the array elements MUST be applied as the type of the value of header instances. -If a header declaration specifies a non-array type for the value of the header (or doesn't specify a type, which is equivalent to specifying a string type), processors MUST interpret this as disallowing multiple instances of that header in the request or response, as appropriate. +If a header declaration specifies a non-array type for the value of the header, or doesn't specify a type (equivalent to specifying a string type), processors MUST disallow multiple instances of that header in the request or response. -If a header declaration specifies an object type or a union of non-scalar types for the value of the header, or if it specifies an array type for the value of the header and the underlying type of the array is an object or array type or a union of non-scalar types, then validation is not defined by RAML; processors MAY default to treating the format of the header value as JSON in applying the type to instances of that header, or they MAY allow other treatments based on annotations. +RAML does not define validation when a header declaration specifies the following types for the value of the header: an object type, a union of non-scalar types, and an array type if the underlying type of the array is an object type, array type, or a union of non-scalar types. Processors MAY default to treating the format of the header value as JSON in applying the type to instances of that header, or they MAY allow other treatments based on annotations. -Note that some headers may also be added by the intermediate client- and server-side systems such as a browser or a proxy. +Some headers can also be added by the intermediate client- and server-side systems, such as a browser or a proxy. -The following example illustrates inheriting headers from a trait, allowing multiple instances of a header, specifying examples, and overriding them when they're applied to a method and a resource. +The following example illustrates inheriting headers from a trait, allowing multiple instances of a header, specifying examples, and overriding the headers when applied to a method and a resource. ```yaml #%RAML 1.0 @@ -1718,7 +1718,7 @@ traits: type: array description: | A department code to be charged. - Multiple such headers are allowed. + Multiple of such headers are allowed. items: pattern: ^\d+\-\w+$ example: 230-OCTO From 1a9f9c55bbc489e7008bb9c4c81eefc2e544fe89 Mon Sep 17 00:00:00 2001 From: krishahn Date: Sat, 23 Apr 2016 21:35:11 -0700 Subject: [PATCH 173/241] copyedit Query Strings and Query Parameters and The Query String as a Whole --- versions/raml-10/raml-10.md | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/versions/raml-10/raml-10.md b/versions/raml-10/raml-10.md index b1beede9..5f0e104d 100644 --- a/versions/raml-10/raml-10.md +++ b/versions/raml-10/raml-10.md @@ -1747,17 +1747,17 @@ traits: ### Query Strings and Query Parameters -An API's methods may support or require a query string in the URL on which they are invoked. The query string in a URL is defined in [RFC3986](https://www.ietf.org/rfc/rfc3986.txt) as the part of the URL following the question mark separator ("?") and preceding any fragment ("#") separator. The query string may be specified either by the OPTIONAL **queryString** property or by the OPTIONAL **queryParameters** property. The queryString and queryParameters properties are mutually exclusive: processors MUST NOT allow both to be specified (explicitly or implicitly) on the same method of the same resource. +An API method can support or require a query string in the URL on which the method is invoked. The query string in a URL is defined in [RFC3986](https://www.ietf.org/rfc/rfc3986.txt) as the part of the URL following the question mark separator ("?") and preceding any fragment ("#") separator. The query string can be specified either by the OPTIONAL **queryString** property or by the OPTIONAL **queryParameters** property. The queryString and queryParameters properties are mutually exclusive: processors MUST NOT allow both to be specified, explicitly or implicitly, on the same method of the same resource. #### The Query String as a Whole -The queryString property is used to specify the query string as a whole, rather than as name-value pairs. Its value is either the name of a data type or an inline data type declaration (including a data type expression). In either case the types at the root of the type hierarchy of the data type MUST all be either a scalar type or the object type, after fully expanding any union type expressions at every level of the type hierarchy. +The queryString property is used to specify the query string as a whole, rather than as name-value pairs. The queryString value is either the name of a data type or an inline data type declaration, including a data type expression. In either case, all types at the root of the type hierarchy of the data type MUST be either a scalar type or the object type, after fully expanding any union type expressions at every level of the type hierarchy. If the type is derived from a scalar type, the query string as a whole MUST be described by the type. -If the type is derived from an object type, processors MUST regard the query string as a URL-encoded serialization of an instance of this object type; that is, the query string must be of the form "parameter1=value1¶meter2=value2&..." where "parameter1", "parameter2", etc. correspond to the properties in the object type, and the values to the corresponding value specifications in the object type. If a value of a property in the object type is an array type, processors MUST interpret this as allowing multiple instances of that query parameter in the query string. In such a case, the underlying type of the array -- namely, the type of the elements of the array -- MUST be applied as the type of the value of instances of this query parameter. +If the type is derived from an object type, processors MUST regard the query string as a URL-encoded serialization of an instance of this object type. The query string must be of the form "parameter1=value1¶meter2=value2&...", where "parameter1", "parameter2", and so on correspond to properties in the object type. Likewise, "value1", "value2", and so on correspond to value specifications in the object type. If a value of a property in the object type is an array type, processors MUST allow multiple instances of that query parameter in the query string. In such a case, the type of the elements of the array MUST be applied as the type of the value of instances of this query parameter. -In the following example, union types and extending from multiple types are used to constrain the query parameters to specific alternatives: +In the following example, union types and extended multiple types are used to constrain the query parameters to specific alternatives: ```yaml #%RAML 1.0 From 96e8a93952cec6658f5d5824f8532eba0cb6bfb4 Mon Sep 17 00:00:00 2001 From: krishahn Date: Sun, 24 Apr 2016 08:50:26 -0700 Subject: [PATCH 174/241] copyedit Query Parameters in a Query String --- versions/raml-10/raml-10.md | 12 ++++++------ 1 file changed, 6 insertions(+), 6 deletions(-) diff --git a/versions/raml-10/raml-10.md b/versions/raml-10/raml-10.md index b1beede9..ce7085f5 100644 --- a/versions/raml-10/raml-10.md +++ b/versions/raml-10/raml-10.md @@ -1798,17 +1798,17 @@ types: #### Query Parameters in a Query String -The queryParameters property is used to specify the set of query parameters from which the query string is composed. Processors MUST regard the query string as a set of query parameters according to the URL encoding format when applying the restrictions in the API definition. The value of the queryParameters property is an object, specifically a [properties declaration](#property-declarations), as is the value of the properties object of a type declaration. Each property in this declaration object is referred to as a **query parameter declaration**. The name of each such property specifies an allowed query parameter name, while its value specifies the query parameter value's type, as the name of a type or an inline type declaration. +The queryParameters property specifies the set of query parameters from which the query string is composed. When applying the restrictions defined by the API, processors MUST regard the query string as a set of query parameters according to the URL encoding format. The value of the queryParameters property is a [properties declaration](#property-declarations) object, as is the value of the properties object of a type declaration. Each property in this declaration object is referred to as a **query parameter declaration**. Each property name specifies an allowed query parameter name. Each property value specifies the query parameter value type as the name of a type or an inline type declaration. -If a query parameter declaration specifies an array type for the value of the query parameter, processors MUST interpret this as allowing multiple instances of that query parameter in the request or response, as appropriate. In such a case, the underlying type of the array -- namely, the type of the elements of the array -- MUST be applied as the type of the value of instances of this query parameter. +If a query parameter declaration specifies an array type for the value of the query parameter, processors MUST allow multiple instances of that query parameter in the request or response. In this case, the type of the elements of the array MUST be applied as the type of the value of query parameter instances. -If a query parameter declaration specifies a non-array type for the value of the query parameter (or doesn't specify a type, which is equivalent to specifying a string type), processors MUST interpret this as disallowing multiple instances of that query parameter in the request. +If a query parameter declaration specifies a non-array type for the value of the query parameter, or doesn't specify a type (equivalent to specifying a string type), processors MUST disallow multiple instances of that query parameter in the request. -If a query parameter declaration specifies an object type or a union of non-scalar types for the value of the query parameter, or if it specifies an array type for the value of the query parameter and the underlying type of the array is an object type or union of non-scalar types, then processors MUST default to treating the format of the query parameter value as JSON in applying the type to instances of that query parameter. +Processors MUST default to treating the format of the query parameter value as JSON in applying the type to instances of a query parameter if a query parameter definition specifies the value of a query parameter as any of the following types: an object type, a union of non-scalar types, or an array type if the underlying type of the array is an object type or union of non-scalar types. -If a query parameter declaration specifies a non-string scalar type or union of non-string scalar types for the value of the query parameter, or if it specifies an array type for the value of the query parameter and the underlying type of the array is a non-string scalar type or union of non-string scalar types, the standard serialization rules for types MUST be invoked in applying the type to instances of that query parameter. +The standard serialization rules for types MUST be invoked in applying the type to instances of a query parameter if the query parameter definition specifies the value of the query parameter as any of the following types: a non-string scalar type, a union of non-string scalar types, or an array type if the underlying type of the array is a non-string scalar type or union of non-string scalar types. -The following example shows a get method that uses HTTP query parameters; it will be sent to https://api.github.com/v3/users?page=1&per_page=50 (assuming the example values are used). +The following example shows a get method that uses HTTP query parameters. Using example values sends a request to https://api.github.com/v3/users?page=1&per_page=50. ```yaml From d43425bfacf93f94f08926c6bcff49b94196e80a Mon Sep 17 00:00:00 2001 From: krishahn Date: Sun, 24 Apr 2016 08:58:52 -0700 Subject: [PATCH 175/241] minor edit --- versions/raml-10/raml-10.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/versions/raml-10/raml-10.md b/versions/raml-10/raml-10.md index 418d75cf..fa547e37 100644 --- a/versions/raml-10/raml-10.md +++ b/versions/raml-10/raml-10.md @@ -1702,7 +1702,7 @@ If a header declaration specifies an array type for the value of the header, pro If a header declaration specifies a non-array type for the value of the header, or doesn't specify a type (equivalent to specifying a string type), processors MUST disallow multiple instances of that header in the request or response. -RAML does not define validation when a header declaration specifies the following types for the value of the header: an object type, a union of non-scalar types, and an array type if the underlying type of the array is an object type, array type, or a union of non-scalar types. Processors MAY default to treating the format of the header value as JSON in applying the type to instances of that header, or they MAY allow other treatments based on annotations. +RAML does not define validation when a header declaration specifies any of the following types for the value of the header: an object type, a union of non-scalar types, or an array type if the underlying type of the array is an object type, array type, or a union of non-scalar types. Processors MAY default to treating the format of the header value as JSON in applying the type to instances of that header, or they MAY allow other treatments based on annotations. Some headers can also be added by the intermediate client- and server-side systems, such as a browser or a proxy. From 95580b7bb84a8748a6daaf2d9023b91df555f0a4 Mon Sep 17 00:00:00 2001 From: krishahn Date: Sun, 24 Apr 2016 14:04:49 -0700 Subject: [PATCH 176/241] copyedit Method Level Protocols section and Bodies section --- versions/raml-10/raml-10.md | 6 ++---- 1 file changed, 2 insertions(+), 4 deletions(-) diff --git a/versions/raml-10/raml-10.md b/versions/raml-10/raml-10.md index b1beede9..5ad9fda2 100644 --- a/versions/raml-10/raml-10.md +++ b/versions/raml-10/raml-10.md @@ -1836,7 +1836,7 @@ baseUri: https://api.github.com/{version} ### Method-level Protocols -A method can explicitly set the OPTIONAL **protocols** property to specify the protocol(s) used to invoke it, thereby overriding the protocols set elsewhere, e.g. in the baseUri or the root-level **properties** property. +A method can explicitly set the OPTIONAL **protocols** property to specify the protocol(s) used to invoke it, thereby overriding the protocols set elsewhere, for example in the baseUri or the root-level **properties** property. In the following example, the get method is accessible through both HTTP and HTTPS, while the rest of the API requires HTTPS. @@ -1856,9 +1856,7 @@ baseUri: https://api.twitter.com/{version} The HTTP request **body** for a method is specified using the OPTIONAL body property. For example, to create a resource using a POST or PUT, the body of the request would usually include the details of the resource to be created. -The value of the body property is termed a **body declaration**. The body declaration is an object whose property names are the valid media types of the request body and whose property values are the corresponding data type declaration or data type name describing the request body. If [default media types](#default-media-type) has been declared at the root of the API, then the body declaration may alternatively be directly the data type declaration or data type name describing the request body for that media type. - -In the first case above, when the property names represent media types, each property name MUST be a media type string conforming to the media type specification in [RFC6838](#https://tools.ietf.org/html/rfc6838). +The value of the body property is a **body declaration**. Generally, the body declaration is an object whose property names are the valid media types of the request body. Each property name MUST be a media type string conforming to the media type specification in [RFC6838](#https://tools.ietf.org/html/rfc6838). The property values are the corresponding data type declaration or data type name describing the request body. Alternatively, if [default media types](#default-media-type) have been declared at the root of the API, then the body declaration can consist of just the data type declaration or data type name describing the request body for that media type. The following example illustrates various combinations of both default and non-default media types, and both data type declarations and references. From 5ed68962047f33170bcc67482833d5a06643cacd Mon Sep 17 00:00:00 2001 From: krishahn Date: Sun, 24 Apr 2016 15:29:12 -0700 Subject: [PATCH 177/241] copyedit Responses section --- versions/raml-10/raml-10.md | 18 +++++++++--------- 1 file changed, 9 insertions(+), 9 deletions(-) diff --git a/versions/raml-10/raml-10.md b/versions/raml-10/raml-10.md index b1beede9..765e1092 100644 --- a/versions/raml-10/raml-10.md +++ b/versions/raml-10/raml-10.md @@ -1889,24 +1889,24 @@ types: ## Responses -The resources and methods sections of this document have so far described HTTP requests. This section describes the HTTP responses to method invocations on resources. +The resources and methods sections of this document describe HTTP requests. This section describes the HTTP responses to method invocations on resources. -The OPTIONAL **responses** property of a method on a resource describes the possible responses to invoking that method on that resource. Its value is an object whose property names are the possible HTTP status codes for that method on that resource, and whose property values describe the corresponding responses. Each such value is termed a **response declaration**. +The OPTIONAL **responses** property of a method on a resource describes the possible responses to invoking that method on that resource. The value of **responses** is an object that has properties named after possible HTTP status codes for that method on that resource. The property values describe the corresponding responses. Each value is a **response declaration**. -Note that the properties of the responses object are often numeric, e.g. 200 or 204. Processors MUST treat these numeric keys as string keys for all purposes. For example, '200' and 200 MUST be treated as equivalent property keys and therefore not both would be allowed simultaneously since they would constitute duplicate properties. +Properties of the responses object are often numeric, for example 200 or 204. Processors MUST treat these numeric keys as string keys in all situations. For example, '200' and 200 MUST be treated as duplicate property keys, and therefore, are not allowed simultaneously. -The value of a response declaration is an object that may contain any of the following properties. +The value of a response declaration is an object that can contain any of the following properties: |Property | Description | |:--------|:------------| -| description? | A longer, human-friendly description of the response -| (<annotationName>) | Annotations to be applied to this response. Annotations are any property whose key begins with "(" and ends with ")" and whose name (the part between the beginning and ending parentheses) is a declared annotation name. See section [Annotations](#annotations) for more information. +| description? | A human-friendly description of the response +| (<annotationName>) | [Annotations](#annotations) to be applied to this response. An annotation is a property having a key that begins with "(" and ends with ")". The text enclosed in parentheses is the annotation name. | headers? | Detailed information about any response headers returned by this method -| body? | The body of the response +| body? | The body of the response -The OPTIONAL properties **description**, **headers**, **body**, and **annotations** have the same syntax and semantics as they do for [method declarations](methods), but applied to HTTP responses rather than HTTP requests. +The syntax and semantics of the OPTIONAL properties **description**, **headers**, **body**, and **annotations** for responses and [method declarations](methods) are the same, but applied to HTTP responses rather than HTTP requests, respectively. -The following example illustrates some possible responses. +The following example illustrates some possible responses: ```yaml #%RAML 1.0 From b2fb552dc5e61f81d638ce1dc5c841ce642f1c5c Mon Sep 17 00:00:00 2001 From: krishahn Date: Sun, 24 Apr 2016 15:59:09 -0700 Subject: [PATCH 178/241] copyedit resource types and traits --- versions/raml-10/raml-10.md | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/versions/raml-10/raml-10.md b/versions/raml-10/raml-10.md index b1beede9..c69e1309 100644 --- a/versions/raml-10/raml-10.md +++ b/versions/raml-10/raml-10.md @@ -1950,13 +1950,13 @@ types: ## Resource Types and Traits -There are many advantages to reusing patterns across multiple resources and methods. For example, after defining a collection-type resource's characteristics, that definition can be applied to multiple resources. This use of patterns encourages consistency and reduces complexity for both servers and clients. +There are many advantages of reusing patterns across multiple resources and methods. For example, the characteristics of a collection-type resource can be defined and then applied to multiple resources. This use of patterns encourages consistency and reduces complexity for servers and clients. -Moreover, resource and method declarations are frequently repetitive. For example, an API that requires OAuth authentication might require an X-Access-Token header for all methods across all resources. For many reasons it may be preferable to define such a pattern in a single place and apply it consistently everywhere. +Moreover, resource and method declarations are frequently repetitive. For example, an API that requires OAuth authentication might require an X-Access-Token header for all methods across all resources. For many reasons, it might be preferable to define such a pattern in a single place and apply it consistently everywhere. -A resource type, like a resource, can specify security schemes and methods and other properties. Resources that use a resource type inherit its properties. A resource type can also use, and thus inherit from, another resource type. Resource types and resources are related through an inheritance chain pattern. Resource type definitions MUST NOT incorporate nested resources; they cannot be used to generate nested resources when they are applied to a resource, and they do not apply to its existing nested resources. +A resource type, like a resource, can specify security schemes, methods, and other properties. A resource that uses a resource type inherits its properties. A resource type can also use, and thus inherit from, another resource type. Resource types and resources are related through an inheritance chain pattern. A resource type definition MUST NOT incorporate nested resources. A resource type definition cannot be used to generate nested resources when the definition is applied to a resource. A resource type definition does not apply to its own existing nested resources. -A trait, like a method, can provide method-level properties such as description, headers, query string parameters, and responses. Methods that use one or more traits inherit those traits' properties. Resources and resource types can also use, and thus inherit from, one or more traits, which then apply to all of their methods. Traits are related to methods through a mixing pattern. +A trait, like a method, can provide method-level properties such as description, headers, query string parameters, and responses. Methods that use one or more traits inherit properties of those traits. A resource and resource type can also use, and thus inherit from, one or more traits, which then apply to all methods of the resource and resource type. Traits are related to methods through a mixing pattern. ### Declaration Resource Types and Traits From 7b5bdb14151676a493184e4ae0261c475a895bee Mon Sep 17 00:00:00 2001 From: krishahn Date: Sun, 24 Apr 2016 19:21:40 -0700 Subject: [PATCH 179/241] copyedit Declaration Resource Types and Traits --- versions/raml-10/raml-10.md | 12 ++++++------ 1 file changed, 6 insertions(+), 6 deletions(-) diff --git a/versions/raml-10/raml-10.md b/versions/raml-10/raml-10.md index b1beede9..30d500cf 100644 --- a/versions/raml-10/raml-10.md +++ b/versions/raml-10/raml-10.md @@ -1960,17 +1960,17 @@ A trait, like a method, can provide method-level properties such as description, ### Declaration Resource Types and Traits -Resource types may be declared via the OPTIONAL **resourceTypes** property at the root of the API definition. The value of this property is an object whose property names become names of resource types that can be referenced throughout the API, and whose property values are resource type declarations. +Resource types can be declared using the OPTIONAL **resourceTypes** property at the root of the API definition. The value of this property is an object. Its property names become names of resource types that can be referenced throughout the API. Its property values are resource type declarations. -Similarly, traits may be declared via the OPTIONAL **traits** property at the root of the API definition. The value of this property is an object whose property names become names of traits that can be referenced throughout the API, and whose property values are trait declarations. +Similarly, traits can be declared using the OPTIONAL **traits** property at the root of the API definition. The value of this property is an object. Its property names become names of traits that can be referenced throughout the API. Its property values are trait declarations. -Resource type and trait declarations can have the following properties, in addition to all the properties that resources and methods may have, respectively (except that resource type declarations MUST NOT have nested resource properties). +Resource type and trait declarations can have the following properties, in addition to all the properties that resources and methods can have, respectively (except that resource type declarations MUST NOT have nested resource properties). | Property | Definition | |:---------|:-----------| -| usage? | The OPTIONAL **usage** property of a resource type or trait provides instructions on how and when the resource type or trait should be used. Documentation generators MUST convey this property as characteristics of the resource and method, respectively. However, the resources and methods MUST NOT inherit the usage property: neither resources nor methods allow a property named usage. +| usage? | The OPTIONAL **usage** property of a resource type or trait provides instructions about how and when the resource type or trait should be used. Documentation generators MUST describe this property in terms of the characteristics of the resource and method, respectively. However, the resources and methods MUST NOT inherit the usage property. Neither resources nor methods allow a property named usage. -The following example illustrates the declaration of several resource types and traits. +The following example illustrates the declaration of several resource types and traits: ```yaml #%RAML 1.0 @@ -1995,7 +1995,7 @@ traits: required: true ``` -The following example builds on the previous one, but the the resource types and traits are defined in external files that are included by using an !include tag. +The following example builds on the previous one, but the resource types and traits are defined in external files that are included by using an !include tag. ```yaml #%RAML 1.0 From dc925ad8bc3edbf31c02819c3d6492af4de9e6d8 Mon Sep 17 00:00:00 2001 From: krishahn Date: Sun, 24 Apr 2016 19:50:42 -0700 Subject: [PATCH 180/241] copyedit Applying Resource Types and Traits --- versions/raml-10/raml-10.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/versions/raml-10/raml-10.md b/versions/raml-10/raml-10.md index b1beede9..9978200b 100644 --- a/versions/raml-10/raml-10.md +++ b/versions/raml-10/raml-10.md @@ -2022,9 +2022,9 @@ resourceTypes: ### Applying Resource Types and Traits -Resources may specify the resource type from which they inherit using the OPTIONAL **type** property. The resource type MUST be the name of a resource type defined within the root-level resourceTypes property or in a library. Resource type definitions do not apply to existing nested resources. +A resource can specify the resource type from which it is derived using the OPTIONAL **type** property. The resource type MUST be the name of a resource type defined within the root-level resourceTypes property or in a library. Resource type definitions do not apply to existing nested resources. -Similarly, methods may specify one or more traits from which they inherit using the OPTIONAL **is** property. Its value is an array of any number of elements where each MUST be the name of a trait defined within the root-level traits property or in a library. A trait may also be applied to a resource by using the **is** property, which is equivalent to applying the trait to all methods for that resource, whether declared explicitly in the resource definition or inherited from a resource type. The order of a trait getting applied to a method is from left to right; according to the traits defined in the **is** property. Trait definitions do not apply to nested resources. +Similarly, a method can specify one or more traits it inherits using the OPTIONAL **is** property. The value of a trait is an array of any number of elements where each MUST be the name of a trait defined within the root-level traits property or in a library. A trait can also be applied to a resource by using the **is** property. Using this property is equivalent to applying the trait to all methods for that resource, whether declared explicitly in the resource definition or inherited from a resource type. A trait is applied to a method in left-to-right order, according to the traits defined in the **is** property. Trait definitions do not apply to nested resources. The following example illustrates the application of resource types and traits. @@ -2047,7 +2047,7 @@ traits: post: # this method is also secured ``` -To pass parameter values to resource types and traits, use a map when declaring the resource type or trait to be used, as illustrated in the following example. +To pass parameter values to resource types and traits, use a map when declaring the resource type or trait, as illustrated in the following example. ```yaml #%RAML 1.0 From e5ae4fd6a4415d359bd820179b81e4fc1fd6d3af Mon Sep 17 00:00:00 2001 From: krishahn Date: Mon, 25 Apr 2016 13:14:55 -0700 Subject: [PATCH 181/241] copyedit Resource Type and Trait Parameters --- versions/raml-10/raml-10.md | 24 ++++++++++++------------ 1 file changed, 12 insertions(+), 12 deletions(-) diff --git a/versions/raml-10/raml-10.md b/versions/raml-10/raml-10.md index b1beede9..ebf04e62 100644 --- a/versions/raml-10/raml-10.md +++ b/versions/raml-10/raml-10.md @@ -2078,22 +2078,22 @@ traits: ### Resource Type and Trait Parameters -The declarations of resource types and traits MAY contain parameters, whose values MUST be specified when applying the resource type or trait, UNLESS the parameter corresponds to a reserved parameter name, in which case its value MUST be provided by the processing application. - -Parameters are indicated in resource type and trait definitions by double angle brackets (double chevrons) enclosing the parameter name; for example, <>. +The declarations of resource types and traits MAY contain parameters having values that MUST be specified when applying the resource type or trait, UNLESS the parameter name is reserved, in which case its value MUST be provided by the processing application. In resource type and trait declarations, there are two reserved parameter names: **resourcePath** and **resourcePathName**. | Parameter | Value | |:---------|:-----------| -| resourcePath | The resource's full URI relative to the baseUri (if any) -| resourcePathName | The rightmost path fragment of the resource's relative URI, omitting any parametrizing brackets ("{" and "}") +| resourcePath | The full resource URI relative to the baseUri if there is one +| resourcePathName | The rightmost path fragment of the relative resource URI, omitting any parametrizing brackets ("{" and "}") + +Double angle brackets (double chevrons) enclose a parameter name in resource type and trait definitions; for example, `<>`. -A processing application MUST set the value of <> to the concatenation of the inheriting resource's relative URI with all its parent resources' relative URIs, that is, to its URI relative to the baseUri (if any). For example, a resource /users nested in a resource /{groupId} nested in a root-level resource /groups, and applying a resource type or trait that uses the resourcePath parameter, would have the value of that parameter set to /groups/{groupId}/users. +A processing application MUST set the value of `<>` to the concatenation of the relative (to the baseUri if there is one) resource URI of the inheriting resource and all its parent relative resource URIs. A processing application MUST set the value of `<>` at the position in the URI following the rightmost slash ("/"), omitting any parametrizing brackets ("{" and "}"). -A processing application MUST set the value of <> to the part of the inheriting resource's relative URI following the rightmost slash ("/"), after omitting any parametrizing brackets ("{" and "}"). For example, a resource /jobs/{jobId} applying a resource type or trait that uses the resourcePathName parameter would have the value of that parameter set to jobId. +For example, applying a resource type or trait to a resource /users nested in a resource /{groupId} nested in a root-level resource /groups sets the value of the resourcePath parameter to /groups/{groupId}/users. Applying a resource type or trait to a resource /jobs/{jobId} sets the value of the resourcePathName parameter to jobId. -Processing applications MUST also omit any ext parameter and its parametrizing brackets ("{" and "}") found in the resource's URI when setting resourcePath and resourcePathName. For example, a root-level resource /bom/{itemId}{ext} applying a resource type or trait that uses the resourcePathName and resourcePath parameters would have the value of those parameters set to /bom/{itemId} and itemId, respectively. +When setting resourcePath and resourcePathName, processing applications MUST also omit any ext parameter and its parametrizing brackets ("{" and "}") found in the resource URI. For example, applying a resource type or trait to a root-level resource /bom/{itemId}{ext} sets the value of resourcePathName and resourcePath parameters to /bom/{itemId} and itemId, respectively. In trait declarations, there is an additional reserved parameter named **methodName**. @@ -2101,9 +2101,9 @@ In trait declarations, there is an additional reserved parameter named **methodN |:---------|:-----------| | methodName | The name of the method -The processing application MUST set the value of the methodName parameter to the inheriting method's name. +The processing application MUST set the value of the methodName parameter to the inheriting method name. -Parameter values MAY further be transformed by applying one of the following functions. The only locale supported by this version of RAML is United States English. +Parameter values MAY be transformed further by applying one of the following functions. The only locale supported by this version of RAML is United States English. | Function | Definition | |:---------|:-----------| @@ -2118,7 +2118,7 @@ Parameter values MAY further be transformed by applying one of the following fun | !lowerhyphencase | The !lowerhyphencase function MUST convert the value of the parameter to lowercase letters; if the value is a compound word, the function MUST also add an additional hyphen between consecutive words which are not already separated by one or more hyphen.

      for example: `userId --> user-id` | !upperhyphencase | The !upperhyphencase function MUST convert the value of the parameter to uppercase letters; if the value is a compound word, the function MUST also add an additional hyphen between consecutive words which are not already separated by one or more hyphen.

      for example: `userId --> USER-ID` -To apply these functions, append them to the parameter name within the double angle brackets, separated from the parameter name with a pipe ("|") character and optional whitespace padding. Here is an example that uses both functions as well as reserved parameters: +Append these functions to the parameter name within the double angle brackets, separated from the parameter name with a pipe ("|") character and optional whitespace padding. Here is an example that uses functions and reserved parameters: ```yaml #%RAML 1.0 @@ -2155,7 +2155,7 @@ traits: example: <>=h8duh3uhhu38 # e.g. get=h8duh3uhhu38 ``` -Parameters may not be used within !include tags, that is, within the location of the file to be included. +Parameters cannot be used within an !include tag specification of the include file location. ### Declaring HTTP Methods as Optional From f096fa1b194643240e3a93cf7aeaf45b6162cd9d Mon Sep 17 00:00:00 2001 From: krishahn Date: Mon, 25 Apr 2016 13:29:40 -0700 Subject: [PATCH 182/241] minor edits --- versions/raml-10/raml-10.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/versions/raml-10/raml-10.md b/versions/raml-10/raml-10.md index ebf04e62..621ddca0 100644 --- a/versions/raml-10/raml-10.md +++ b/versions/raml-10/raml-10.md @@ -2080,7 +2080,7 @@ traits: The declarations of resource types and traits MAY contain parameters having values that MUST be specified when applying the resource type or trait, UNLESS the parameter name is reserved, in which case its value MUST be provided by the processing application. -In resource type and trait declarations, there are two reserved parameter names: **resourcePath** and **resourcePathName**. +In resource type and trait declarations, **resourcePath** and **resourcePathName** are reserved parameter names. | Parameter | Value | |:---------|:-----------| @@ -2095,7 +2095,7 @@ For example, applying a resource type or trait to a resource /users nested in a When setting resourcePath and resourcePathName, processing applications MUST also omit any ext parameter and its parametrizing brackets ("{" and "}") found in the resource URI. For example, applying a resource type or trait to a root-level resource /bom/{itemId}{ext} sets the value of resourcePathName and resourcePath parameters to /bom/{itemId} and itemId, respectively. -In trait declarations, there is an additional reserved parameter named **methodName**. +In trait declarations, **methodName** is a reserved parameter. | Parameter | Value | |:---------|:-----------| @@ -2118,7 +2118,7 @@ Parameter values MAY be transformed further by applying one of the following fun | !lowerhyphencase | The !lowerhyphencase function MUST convert the value of the parameter to lowercase letters; if the value is a compound word, the function MUST also add an additional hyphen between consecutive words which are not already separated by one or more hyphen.

      for example: `userId --> user-id` | !upperhyphencase | The !upperhyphencase function MUST convert the value of the parameter to uppercase letters; if the value is a compound word, the function MUST also add an additional hyphen between consecutive words which are not already separated by one or more hyphen.

      for example: `userId --> USER-ID` -Append these functions to the parameter name within the double angle brackets, separated from the parameter name with a pipe ("|") character and optional whitespace padding. Here is an example that uses functions and reserved parameters: +Append these functions to the parameter name within the double angle brackets, separated by a pipe ("|") character and optional whitespace padding. Here is an example that uses functions and reserved parameters: ```yaml #%RAML 1.0 From 0c7f81602948e60346c4b404628c81f954b5fb3c Mon Sep 17 00:00:00 2001 From: krishahn Date: Mon, 25 Apr 2016 15:52:19 -0700 Subject: [PATCH 183/241] copyedit Declaring HTTP Methods as Optional --- versions/raml-10/raml-10.md | 9 ++++++--- 1 file changed, 6 insertions(+), 3 deletions(-) diff --git a/versions/raml-10/raml-10.md b/versions/raml-10/raml-10.md index b1beede9..4f2987bd 100644 --- a/versions/raml-10/raml-10.md +++ b/versions/raml-10/raml-10.md @@ -2159,11 +2159,14 @@ Parameters may not be used within !include tags, that is, within the location of ### Declaring HTTP Methods as Optional -When defining resource types, it can be useful to capture patterns that manifest several levels below the inheriting resource, without mandating the creation of the intermediate levels. For example, a resource type declaration may describe a body parameter that would be used if the API defines a post method for that resource, but applying the resource type to a resource without a post method should not create the post method. +When defining resource types, it can be useful to capture patterns that manifest several levels below the inheriting resource without mandating the creation of the intermediate levels. For example, a resource type declaration describes a body parameter that is used if the API defines a post method for that resource. Applying the resource type to a resource without a post method does not create the post method. -To accommodate this need, a resource type definition MAY append a question mark ("?") suffix to the name of any method that should not be applied if it doesn't already exist in the resource at the corresponding level. The question mark suffix indicates that the value of the method property in the resource type should be applied if the method name itself (without the question mark) is already defined (whether explicitly or implicitly) at the corresponding level in that resource. +To accommodate this need, a resource type definition MAY append a question mark ("?") suffix to the name of any method to declare the method as optional, resulting in the following behavior: -The following example shows a resource type called corpResource with an optional post? property that defines a required header called X-Chargeback and also a custom parameter called TextAboutPost. If the inheriting resource defines a post method, it will include the X-Chargeback header requirement and TextAboutPost MUST be defined as well. If the inheriting resource does not define a post method, one will not have to define the X-Chargeback header or be forced to define the TextAboutPost parameter by dint of inheriting from the corpResource resource type. +* Apply the method to the resource if it doesn't already exist at the corresponding level. +* Apply the value of the method property to the resource type if the method name without the question mark is already defined, explicitly or implicitly, at the corresponding level in that resource. + +The following example shows a resource type called corpResource with an optional post? property that defines a required header called X-Chargeback and a custom parameter called TextAboutPost. The inheriting resource /servers defines a post method, so it needs to include the X-Chargeback header requirement. TextAboutPost MUST be defined as well. The inheriting resource /queues does not define a post method, so it does not have to define the X-Chargeback header or the TextAboutPost parameter. ```yaml #%RAML 1.0 From a112af4d8a96ecfa2d556dbaf9ab3ce52d2670b7 Mon Sep 17 00:00:00 2001 From: krishahn Date: Mon, 25 Apr 2016 16:03:49 -0700 Subject: [PATCH 184/241] correction apply > do not apply --- versions/raml-10/raml-10.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/versions/raml-10/raml-10.md b/versions/raml-10/raml-10.md index 4f2987bd..b7ee4054 100644 --- a/versions/raml-10/raml-10.md +++ b/versions/raml-10/raml-10.md @@ -2163,8 +2163,8 @@ When defining resource types, it can be useful to capture patterns that manifest To accommodate this need, a resource type definition MAY append a question mark ("?") suffix to the name of any method to declare the method as optional, resulting in the following behavior: -* Apply the method to the resource if it doesn't already exist at the corresponding level. -* Apply the value of the method property to the resource type if the method name without the question mark is already defined, explicitly or implicitly, at the corresponding level in that resource. +* Do not apply the method to the resource if it doesn't already exist at the corresponding level in the resource. +* Apply the value of the method property to the resource type if the method name without the question mark is already defined, explicitly or implicitly, at the corresponding level in the resource. The following example shows a resource type called corpResource with an optional post? property that defines a required header called X-Chargeback and a custom parameter called TextAboutPost. The inheriting resource /servers defines a post method, so it needs to include the X-Chargeback header requirement. TextAboutPost MUST be defined as well. The inheriting resource /queues does not define a post method, so it does not have to define the X-Chargeback header or the TextAboutPost parameter. From 89438b6a6ace6466a95eaea3ed044e4d53a200b5 Mon Sep 17 00:00:00 2001 From: krishahn Date: Mon, 25 Apr 2016 16:56:07 -0700 Subject: [PATCH 185/241] copyedit algorithm-of-merging-traits-with-methods --- versions/raml-10/raml-10.md | 49 ++++++++++++++++++------------------- 1 file changed, 24 insertions(+), 25 deletions(-) diff --git a/versions/raml-10/raml-10.md b/versions/raml-10/raml-10.md index b1beede9..6456a628 100644 --- a/versions/raml-10/raml-10.md +++ b/versions/raml-10/raml-10.md @@ -2188,33 +2188,32 @@ resourceTypes: # not required; same for the X-Chargeback header ``` -### Algorithm of Merging Traits With Methods - -Each RAML element has its branch of the RAML document. Informally, applying a trait to method may be described as putting traits branch under the methods branch. -Formally, it is a recursive procedure: -1. Those properties of method node which are undefined in trait node remain unchanged. -2. The method node receives all properties of trait node (excluding optional) which are undefined in method node. -3. As for properties defined in both method node and trait node (including optional): - * Scalar properties remain unchanged - * Collection properties are merged by value (see below) - * Values of object properties are subjected to the same procedure starting at step 1. - -In general case a method can have more than one trait each having a sufficient hierarchy. Applying all of them is equivalent to building a stack of branches: - -1. Top branch is the methods branch. -2. Other branches are traits branches. - * Branches of those traits which are farther from the method in hierarchical sense, lay deeper (a trait may occur on different hierarchy distances, and we consider the closest one). - * Those traits which lay on the same hierarchy distance from the method, can be ordered in a queue: - * For distance one it's just the methods trait list. - * Queue(d+1) is obtained from Queue(d) by concatenating trait lists of its elements and canceling all but the first occurence of each trait. - * Branches order is determined as follows: those traits, which have higher positions in the queue, also have their branches deeper in our stack. - -Finally, the resource can have its own traits, and it can be applied a chain of resource types (call them resourceType1, resourceType2, etc), each possibly having its own traits and defining the same method. The stack is constructed as follows: +### Algorithm of Merging Traits and Methods + +Each RAML element has its branch of the RAML document. The high-level description of applying a trait to method is putting a traits branch under the methods branch. Actually, applying a trait to a method is a recursive procedure: +1. Method node properties are inspected and those that are undefined in trait node remain unchanged. +2. The method node receives all properties of trait node (excluding optional ones), which are undefined in the method node. +3. Properties defined in both method node and trait node (including optional ones) are treated as follows: + * Scalar properties remain unchanged. + * Collection properties are merged by value, as described later. + * Values of object properties are subjected to steps 1-3 of this procedure. + +Generally, a method can have more than one trait, each having a sufficient hierarchy. Applying all traits is equivalent to building a stack of branches as follows: + +* The top branch is the methods branch. +* Other branches are traits branches. + * Branches of traits that are farther away hierarchically from the method than others, are bypassed in favor the closest one. + * Those traits that are within the same hierarchy distance from the method, can be ordered in a queue: + * For distance one, it's just the methods trait list. + * Queue(d+1) is obtained from Queue(d) by concatenating trait lists of its elements and canceling all but the first occurrence of each trait. + * Branch order is determined as follows: traits that have higher positions in the queue, have branches deeper in the stack. + +Finally, the resource can have its own traits, and a chain of resource types, for example resourceType1, resourceType2, ..., can be applied. Each resource type can potentially have its own traits and define the same method. The stack is constructed as follows: 1. Traits of method itself 2. Traits of resource owning the method 3. Traits of method owned by resourceType1 4. Traits of resourceType1 -5. etc. +5. ... Merging resource types with resources obeys similar rules. @@ -2237,9 +2236,9 @@ resourceTypes: application/json: ``` -The only overlap between the `collection` resource type and the resource declaration is `description` which is defined in both. In this example, the final version will have the description that has been explicitly defined in the resource. +The only overlap between the `collection` resource type and the resource declaration is `description` which is defined in both. In this example, the final version has the description that has been explicitly defined in the resource. -Every explicit node will win over the ones that are declared in a resource type or trait. The rest is simply merged. The final merged result must be: +Every explicit node wins over the ones that are declared in a resource type or trait. The rest are simply merged. The final, merged result must be: ```yaml /resource: From fbf3f1f7313593c3801efe3688b27b0691e943a5 Mon Sep 17 00:00:00 2001 From: krishahn Date: Mon, 25 Apr 2016 21:12:01 -0700 Subject: [PATCH 186/241] format numbered steps --- versions/raml-10/raml-10.md | 24 +++++++++++++----------- 1 file changed, 13 insertions(+), 11 deletions(-) diff --git a/versions/raml-10/raml-10.md b/versions/raml-10/raml-10.md index 6456a628..8a9d829b 100644 --- a/versions/raml-10/raml-10.md +++ b/versions/raml-10/raml-10.md @@ -2191,12 +2191,13 @@ resourceTypes: ### Algorithm of Merging Traits and Methods Each RAML element has its branch of the RAML document. The high-level description of applying a trait to method is putting a traits branch under the methods branch. Actually, applying a trait to a method is a recursive procedure: -1. Method node properties are inspected and those that are undefined in trait node remain unchanged. -2. The method node receives all properties of trait node (excluding optional ones), which are undefined in the method node. -3. Properties defined in both method node and trait node (including optional ones) are treated as follows: - * Scalar properties remain unchanged. - * Collection properties are merged by value, as described later. - * Values of object properties are subjected to steps 1-3 of this procedure. + +1. Method node properties are inspected and those that are undefined in trait node remain unchanged. +2. The method node receives all properties of trait node (excluding optional ones), which are undefined in the method node. +3. Properties defined in both method node and trait node (including optional ones) are treated as follows: + * Scalar properties remain unchanged. + * Collection properties are merged by value, as described later. + * Values of object properties are subjected to steps 1-3 of this procedure. Generally, a method can have more than one trait, each having a sufficient hierarchy. Applying all traits is equivalent to building a stack of branches as follows: @@ -2209,11 +2210,12 @@ Generally, a method can have more than one trait, each having a sufficient hiera * Branch order is determined as follows: traits that have higher positions in the queue, have branches deeper in the stack. Finally, the resource can have its own traits, and a chain of resource types, for example resourceType1, resourceType2, ..., can be applied. Each resource type can potentially have its own traits and define the same method. The stack is constructed as follows: -1. Traits of method itself -2. Traits of resource owning the method -3. Traits of method owned by resourceType1 -4. Traits of resourceType1 -5. ... + +1. Traits of method itself +2. Traits of resource owning the method +3. Traits of method owned by resourceType1 +4. Traits of resourceType1 +5. ... Merging resource types with resources obeys similar rules. From 3ade44ea02f9aab555c763ab1d838a21a0f97096 Mon Sep 17 00:00:00 2001 From: krishahn Date: Mon, 25 Apr 2016 22:01:02 -0700 Subject: [PATCH 187/241] copyedit resource-types-and-traits-effect-on-collections --- versions/raml-10/raml-10.md | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/versions/raml-10/raml-10.md b/versions/raml-10/raml-10.md index b1beede9..b8384e0c 100644 --- a/versions/raml-10/raml-10.md +++ b/versions/raml-10/raml-10.md @@ -2255,7 +2255,7 @@ Every explicit node will win over the ones that are declared in a resource type ### Resource Types and Traits Effect on Collections -All the collections or sequences which fall under effect of applying traits and resource types are merged. Consider an example of query parameter which has its enum values defined in both resource and trait: +All collections or sequences that are affected by applied traits and resource types are merged. This example defines the enum values of a query parameter in both the trait and resource: ```yaml #%RAML 1.0 @@ -2278,9 +2278,9 @@ traits: - unix ``` -In this example the resulting enum value is `[ mac, unix, win ]`. +The enum value resulting from the merge that occurs is `[ mac, unix, win ]`. -Important case of collections is a trait, which can appear as "is" attribute value for method, resource, trait or resource type. Such lists may contain same traits which differ in parameter sets and, thus, can not be considered equal: +In collections, a trait can appear as an "is" attribute value for a method, resource, trait, or resource type. Such lists can contain the same traits but different parameter sets and, thus, cannot be considered equal: ```yaml #%RAML 1.0 @@ -2300,7 +2300,7 @@ traits: is: [ { secured : { tokenName: token } } ] ``` -In resolving such a collision priority is given to that trait occurrence which is closer to the target method (or resource). In the example above the `tokenName` parameter value for the `GET:/servers` method is `token`, and the trait list consists of single trait occurrence: `[ {secured:{ tokenName:token}} ]`. +To resolve a collision arising from this inequality, priority is given to the trait in closest proximity to the target method or resource. In the previous example, the `tokenName` parameter value for the `GET:/servers` method is `token`, and the trait list consists of single trait occurrence: `[ {secured:{ tokenName:token}} ]`. ## Security Schemes From 4bf196c58a888120f0d7b4f4464ed14859510c78 Mon Sep 17 00:00:00 2001 From: Christian Vogel Date: Tue, 26 Apr 2016 10:03:32 +0100 Subject: [PATCH 188/241] removed displayName and description section for resources --- versions/raml-10/raml-10.md | 12 ++---------- 1 file changed, 2 insertions(+), 10 deletions(-) diff --git a/versions/raml-10/raml-10.md b/versions/raml-10/raml-10.md index b7728dab..799981ce 100644 --- a/versions/raml-10/raml-10.md +++ b/versions/raml-10/raml-10.md @@ -1522,7 +1522,7 @@ The value of a resource property is an object whose properties are described in |Property | Description | |:--------|:------------| -| displayName? | An alternate, human-friendly name for the resource. +| displayName? | An alternate, human-friendly name for the resource. If the displayName property is not defined for a resource, documentation tools SHOULD refer to the resource by its property key, which acts as the resource name. For example, tools should refer to the relative URI /jobs. | description? | A longer, human-friendly description of the resource. | (<annotationName>)? | [Annotations](#annotations) to be applied to this resource. An annotation is a property having a key that begins with "(" and ends with ")". The text enclosed in parentheses is the annotation name. | get?
      patch?
      put?
      post?
      delete?
      options?
      head? | The object describing the [method](#methods). @@ -1532,17 +1532,9 @@ The value of a resource property is an object whose properties are described in | uriParameters? | Detailed information about any URI parameters of this resource. | /<relativeUri>? | A nested resource, which is identified as any property whose name begins with a slash ("/"), and is therefore treated as a relative URI. -### Resource Display Name - -The OPTIONAL **displayName** property assigns a friendly name to the resource and can be used by documentation generation tools. If the displayName property is not defined for a resource, documentation tools SHOULD refer to the resource by its property key, which acts as the resource name. For example, tools should refer to the relative URI /jobs. - -### Resource Description - -The OPTIONAL **description** property can be used to provide a longer description of the resource. It is RECOMMENDED that all resources provide such a description. - ### Template URIs and URI Parameters -[Template URIs](#template-uri) containing URI parameters can be used to define a relative URI of a resource that contains variable elements. The following example shows a top-level resource with a key /jobs and a nested resource with a key /{jobId}, a template URI. +[Template URIs](#template-uri) containing URI parameters can be used to define a relative URI of a resource that contains variable elements. The following example shows a top-level resource with a key /jobs and a nested resource with a key /{jobId}, a template URI. ```yaml #%RAML 1.0 From c401e9b6b03940916968845a5a2716a6bbd14e12 Mon Sep 17 00:00:00 2001 From: Christian Vogel Date: Tue, 26 Apr 2016 10:12:56 +0100 Subject: [PATCH 189/241] removed display name and description section from method chapter --- versions/raml-10/raml-10.md | 28 +++------------------------- 1 file changed, 3 insertions(+), 25 deletions(-) diff --git a/versions/raml-10/raml-10.md b/versions/raml-10/raml-10.md index db1ce908..f275957a 100644 --- a/versions/raml-10/raml-10.md +++ b/versions/raml-10/raml-10.md @@ -1645,40 +1645,18 @@ RESTful API methods are operations that are performed on a resource. The OPTIONA |Property | Description | |:--------|:------------| -| displayName? | An alternate, human-friendly method name in the context of the resource. -| description? | A longer, human-friendly description of the method in the context of the resource. +| displayName? | An alternate, human-friendly method name in the context of the resource. If the displayName property is not defined for a method, documentation tools SHOULD refer to the resource by its property key, which acts as the method name. +| description? | A longer, human-friendly description of the method in the context of the resource. Its value is a string and MAY be formatted using [markdown](#markdown). | (<annotationName>)? | [Annotations](#annotations) to be applied to this method. An annotation is a property having a key that begins with "(" and ends with ")". The text enclosed in parentheses is the annotation name. | queryParameters? | Detailed information about any query parameters needed by this method. Mutually exclusive with queryString. | headers? | Detailed information about any request headers needed by this method. | queryString? | The query string needed by this method. Mutually exclusive with queryParameters. | responses? | Information about the expected responses to a request. | body? | A request body that the method admits. -| protocols? | The [protocols](#method-level-protocols) that override those specified in the resource or at the API root. +| protocols? | The [protocols](#method-level-protocols) that override those specified in the resource or at the API root. | is? | A list of the [traits](#applying-resource-types-and-traits) to apply to this method. | securedBy? | The [security schemes](#applying-security-schemes) that apply to this method. -### Method-level Display Name - -The OPTIONAL **displayName** property provides a friendly name for the method and can be used by documentation generation tools. If the displayName property is not defined for a method, documentation tools SHOULD refer to the resource by its property key, which acts as the method name. - -### Method-level Description - -The OPTIONAL **description** property describes the operation of the method on the resource. Its value is a string and MAY be formatted using [markdown](#markdown). It is RECOMMENDED that all methods provide such a description. - -The following example shows a resource, /jobs, with post and get methods declared. - -```yaml -#%RAML 1.0 -title: ZEncoder API -version: v2 -baseUri: https://app.zencoder.com/api/{version} -/jobs: - post: - description: Create a *new* job - get: - description: List some or all jobs -``` - ### Headers An API's methods may support or require various HTTP headers. The OPTIONAL **headers** property is used to explicitly specify those headers. The value of the headers property is an object, specifically a [properties declaration](#property-declarations), as is the value of the properties object of a type declaration. Each property in this declaration object is referred to as a header **declaration**. The name of each such property specifies an allowed header name, while its value specifies the header value's type, as the name of a type or an inline type declaration. From 6255b70befe3f7bc4fb5ce61e47a5abff1ce61a1 Mon Sep 17 00:00:00 2001 From: Christian Vogel Date: Tue, 26 Apr 2016 10:23:18 +0100 Subject: [PATCH 190/241] moved content of method-level protocols section into the method table --- versions/raml-10/raml-10.md | 20 +------------------- 1 file changed, 1 insertion(+), 19 deletions(-) diff --git a/versions/raml-10/raml-10.md b/versions/raml-10/raml-10.md index 04a48642..bddbdcd5 100644 --- a/versions/raml-10/raml-10.md +++ b/versions/raml-10/raml-10.md @@ -1645,7 +1645,7 @@ RESTful API methods are operations that are performed on a resource. The OPTIONA | queryString? | The query string needed by this method. Mutually exclusive with queryParameters. | responses? | Information about the expected responses to a request. | body? | A request body that the method admits. -| protocols? | The [protocols](#method-level-protocols) that override those specified in the resource or at the API root. +| protocols? | Explicitly specify the protocol(s) used to invoke a method, thereby overriding the protocols set elsewhere, for example in the baseUri or the [root-level protocols](#protocols) property. | is? | A list of the [traits](#applying-resource-types-and-traits) to apply to this method. | securedBy? | The [security schemes](#applying-security-schemes) that apply to this method. @@ -1804,24 +1804,6 @@ baseUri: https://api.github.com/{version} example: 50 ``` -### Method-level Protocols - -A method can explicitly set the OPTIONAL **protocols** property to specify the protocol(s) used to invoke it, thereby overriding the protocols set elsewhere, for example in the baseUri or the root-level **properties** property. - -In the following example, the get method is accessible through both HTTP and HTTPS, while the rest of the API requires HTTPS. - -```yaml -#%RAML 1.0 -title: Twitter API -version: 1.1 -baseUri: https://api.twitter.com/{version} -/search/tweets.json: - description: Search all tweets - get: - description: Returns a collection of relevant Tweets matching a specified query - protocols: [ HTTP, HTTPS ] -``` - ### Bodies The HTTP request **body** for a method is specified using the OPTIONAL body property. For example, to create a resource using a POST or PUT, the body of the request would usually include the details of the resource to be created. From a4f19bcba3e73bbedfe80f4d9d470c06681ae48b Mon Sep 17 00:00:00 2001 From: Christian Vogel Date: Tue, 26 Apr 2016 10:58:48 +0100 Subject: [PATCH 191/241] clarification how instances get validated against union types --- versions/raml-10/raml-10.md | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/versions/raml-10/raml-10.md b/versions/raml-10/raml-10.md index 24466c72..971d00e8 100644 --- a/versions/raml-10/raml-10.md +++ b/versions/raml-10/raml-10.md @@ -1108,12 +1108,12 @@ types: type: Phone | Notebook ``` -A valid instance of a union type must pass all restrictions associated with at least one of the union type options. For example: +To deserialize an instance, first fully expand all unions at every level, then match the instance against each element in that expansion starting from the left-most and proceeding to the right; use the first successful matching element to deserialize the instance; and if no elements match, the instance is invalid. A valid instance of a union type must pass all restrictions associated with at least one of the elements. For example: ```yaml types: CatOrDog: - type: Cat | Dog # options: Cat or Dog + type: Cat | Dog # elements: Cat or Dog Cat: type: object properties: @@ -1143,7 +1143,7 @@ types: In this case, type `HomeAnimal` has two base types, `HasHome` and an anonymous union type, defined by the following type expression: `Dog | Cat` -Validating the `HomeAnimal` type involves validating the types derived from each of the base types and the types of each union type option. In this particular case, you need to test that types `[HasHome, Dog]` and `[HasHome, Cat]` are valid types. +Validating the `HomeAnimal` type involves validating the types derived from each of the base types and the types of each element in the union type. In this particular case, you need to test that types `[HasHome, Dog]` and `[HasHome, Cat]` are valid types. If you are extending from two union types you should perform validations for every possible combination. For example, to validate the `HomeAnimal` type shown below, you need to test six possible combinations: `[HasHome, Dog ]`, `[HasHome, Cat ]`, `[HasHome, Parrot]`, `[IsOnFarm, Dog ]`, `[IsOnFarm, Cat ]`, and `[IsOnFarm, Parrot]`. @@ -2039,7 +2039,7 @@ In resource type and trait declarations, **resourcePath** and **resourcePathName Double angle brackets (double chevrons) enclose a parameter name in resource type and trait definitions; for example, `<>`. -A processing application MUST set the value of `<>` to the concatenation of the relative (to the baseUri if there is one) resource URI of the inheriting resource and all its parent relative resource URIs. A processing application MUST set the value of `<>` at the position in the URI following the rightmost slash ("/"), omitting any parametrizing brackets ("{" and "}"). +A processing application MUST set the value of `<>` to the concatenation of the relative (to the baseUri if there is one) resource URI of the inheriting resource and all its parent relative resource URIs. A processing application MUST set the value of `<>` at the position in the URI following the rightmost slash ("/"), omitting any parametrizing brackets ("{" and "}"). For example, applying a resource type or trait to a resource /users nested in a resource /{groupId} nested in a root-level resource /groups sets the value of the resourcePath parameter to /groups/{groupId}/users. Applying a resource type or trait to a resource /jobs/{jobId} sets the value of the resourcePathName parameter to jobId. From 80bc592beee37204b46dd80fffc9c8aab6b04472 Mon Sep 17 00:00:00 2001 From: Christian Vogel Date: Tue, 26 Apr 2016 11:01:14 +0100 Subject: [PATCH 192/241] added 'instance of data' --- versions/raml-10/raml-10.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/versions/raml-10/raml-10.md b/versions/raml-10/raml-10.md index 971d00e8..606290c5 100644 --- a/versions/raml-10/raml-10.md +++ b/versions/raml-10/raml-10.md @@ -1108,7 +1108,7 @@ types: type: Phone | Notebook ``` -To deserialize an instance, first fully expand all unions at every level, then match the instance against each element in that expansion starting from the left-most and proceeding to the right; use the first successful matching element to deserialize the instance; and if no elements match, the instance is invalid. A valid instance of a union type must pass all restrictions associated with at least one of the elements. For example: +To deserialize an instance of data, first fully expand all unions at every level, then match the instance against each element in that expansion starting from the left-most and proceeding to the right; use the first successful matching element to deserialize the instance; and if no elements match, the instance is invalid. A valid instance of a union type must pass all restrictions associated with at least one of the elements. For example: ```yaml types: From b23d9a3561e77f2deffca37d80638546db57efa8 Mon Sep 17 00:00:00 2001 From: Christian Vogel Date: Tue, 26 Apr 2016 11:16:54 +0100 Subject: [PATCH 193/241] next changes after discussion in issue 394 --- versions/raml-10/raml-10.md | 13 ++++++++++--- 1 file changed, 10 insertions(+), 3 deletions(-) diff --git a/versions/raml-10/raml-10.md b/versions/raml-10/raml-10.md index 5afdaea1..e0fea66a 100644 --- a/versions/raml-10/raml-10.md +++ b/versions/raml-10/raml-10.md @@ -918,8 +918,12 @@ The ​**file**​ type can constrain the content to send through forms. When th ### Null Type ​ -RAML handles null data values in payloads, annotations, and other constructs. Nullable properties must be represented as a single `null` type, a union of the non-null and `null` types, or suffixing the type with a trailing question mark `?`. +RAML handles null data values in payloads, annotations, and other constructs. Nullable properties must be represented as a single `null` type, a union of the non-null and `null` types, or suffixing the type with a trailing question mark `?`, for example `x?` which is equivalent to `null | x`. + +For headers, URI parameters, and query parameters, only the string value "null" (case-sensitive) validates against the null type, and in turn the string value "null" (case-sensitive) deserializes to the null type. + In the following example, the type of an object and has two required properties, `name` and `comment`, both defaulting to type `string`. In `example`, `name` is assigned a string value, but comment is null and this is _not_ allowed because RAML expects a string. + ```yaml type: properties: @@ -929,7 +933,9 @@ example: name: Fred comment: # Providing no value here is not allowed. ``` + The following example shows the assignment of the `null` type to `comment`: + ​ ```yaml type: @@ -940,20 +946,21 @@ example: name: Fred comment: # Providing a value here is not allowed. ``` + The following example shows how to represent nullable properties using a union: ​ ```yaml type: properties: name: - comment: string | null # equivalent to -> + comment: null | string # equivalent to -> # comment: string? example: name: Fred comment: # Providing a value or not providing a value here is allowed. ``` -Declaring the type of a property to be `null` causes a RAML processor to forbid an instance to have a value. +Declaring the type of a property to be `null` causes a RAML processor to forbid an instance to have a value. In a RAML context that requires *values* of type `null` (vs just type declarations), the usual YAML `null` is used, e.g. when the type is `number | null` you may use `enum: [ 1, 2, ~ ]` or more explicitly/verbosely `enum: [ 1, 2, !!null "" ]`; in non-inline notation you can just omit the value completely, of course. ### User-defined Facets From 235c84960956a414f982fa7b771c01d2af2a83ff Mon Sep 17 00:00:00 2001 From: Christian Vogel Date: Tue, 26 Apr 2016 12:13:44 +0100 Subject: [PATCH 194/241] removed repeated sentence --- versions/raml-10/raml-10.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/versions/raml-10/raml-10.md b/versions/raml-10/raml-10.md index b57705f7..aeacfbad 100644 --- a/versions/raml-10/raml-10.md +++ b/versions/raml-10/raml-10.md @@ -1220,7 +1220,7 @@ Sometimes it is necessary to refer to an element defined in a schema. RAML suppo type: !include elements.xsd#Foo ``` -When referencing an inner element of a schema, a RAML processor MUST validate an instance against that particular element. The structural restrictions on referencing an inner element are the same as those on referencing other elements. This version of RAML specification supports referencing any inner elements in JSON schemas that are valid schemas, any globally defined elements, and complex types in XML schemas. There are only a few restrictions: +When referencing an inner element of a schema, a RAML processor MUST validate an instance against that particular element. This version of RAML specification supports referencing any inner elements in JSON schemas that are valid schemas, any globally defined elements, and complex types in XML schemas. There are only a few restrictions: * Validation of any XML or JSON instance against inner elements follows the same restrictions as the validation against a regular XML or JSON schema. * Referencing complex types inside an XSD is valid to determine the structure of an XML instance, but since complex types do not define a name for the top-level XML element, these types cannot be used for serializing an XML instance. From 2e6c7a9ce1bdc011c0fe3c8e50420a77b08c8c74 Mon Sep 17 00:00:00 2001 From: Christian Vogel Date: Tue, 26 Apr 2016 13:58:28 +0100 Subject: [PATCH 195/241] some wordsmithing for a more clear representation of the question mark suffix --- versions/raml-10/raml-10.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/versions/raml-10/raml-10.md b/versions/raml-10/raml-10.md index e0fea66a..1d72a850 100644 --- a/versions/raml-10/raml-10.md +++ b/versions/raml-10/raml-10.md @@ -918,7 +918,7 @@ The ​**file**​ type can constrain the content to send through forms. When th ### Null Type ​ -RAML handles null data values in payloads, annotations, and other constructs. Nullable properties must be represented as a single `null` type, a union of the non-null and `null` types, or suffixing the type with a trailing question mark `?`, for example `x?` which is equivalent to `null | x`. +RAML handles null data values in payloads, annotations, and other constructs. Nullable properties must be represented as a single `null` type, a union of the non-null and `null` types, or by suffixing the type with a trailing question mark `?` which is the equivalent to a union between `null` and a type, for example: `null | number`. For headers, URI parameters, and query parameters, only the string value "null" (case-sensitive) validates against the null type, and in turn the string value "null" (case-sensitive) deserializes to the null type. From 5f43ddb355ec0895585545ea415b5cababb7f404 Mon Sep 17 00:00:00 2001 From: Christian Vogel Date: Tue, 26 Apr 2016 19:26:17 +0100 Subject: [PATCH 196/241] fix issue with example for user-defined facets that used 'date' as type --- versions/raml-10/raml-10.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/versions/raml-10/raml-10.md b/versions/raml-10/raml-10.md index 7255c169..77bfb7ae 100644 --- a/versions/raml-10/raml-10.md +++ b/versions/raml-10/raml-10.md @@ -933,7 +933,7 @@ Here is an example that defines the capability to restrict dates to those that d title: API with Types types: CustomDate: - type: date + type: date-only facets: onlyFutureDates?: boolean # optional in `PossibleMeetingDate` noHolidays: boolean # required in `PossibleMeetingDate` From 0c5d2888b0353fa70feea3390d571bfe6e67c546 Mon Sep 17 00:00:00 2001 From: krishahn Date: Tue, 26 Apr 2016 14:19:14 -0700 Subject: [PATCH 197/241] copyedit Security Schemes --- versions/raml-10/raml-10.md | 93 ++++++++++++++++++------------------- 1 file changed, 45 insertions(+), 48 deletions(-) diff --git a/versions/raml-10/raml-10.md b/versions/raml-10/raml-10.md index 7255c169..112b6c04 100644 --- a/versions/raml-10/raml-10.md +++ b/versions/raml-10/raml-10.md @@ -2281,35 +2281,33 @@ RAML supports the following built-in security scheme types: |Type |Description| |:----------|:----------| -|OAuth 1.0 | The API's authentication requires using OAuth 1.0 as described in [RFC5849](https://tools.ietf.org/html/rfc5849) -|OAuth 2.0 | The API's authentication requires using OAuth 2.0 as described in [RFC6749](https://tools.ietf.org/html/rfc6749) -|Basic Authentication| The API's authentication relies on using Basic Access Authentication as described in [RFC2617](https://tools.ietf.org/html/rfc2617) -|Digest Authentication| The API's authentication relies on using Digest Access Authentication as described in [RFC2617](https://tools.ietf.org/html/rfc2617) -|Pass Through| Headers or Query Parameters are passed through to the API based on a defined mapping. -|x-{other}| The API's authentication relies on another authentication method. +|OAuth 1.0 | The API authentication requires using OAuth 1.0 as described in [RFC5849](https://tools.ietf.org/html/rfc5849) +|OAuth 2.0 | The API authentication requires using OAuth 2.0 as described in [RFC6749](https://tools.ietf.org/html/rfc6749) +|Basic Authentication| The API authentication relies on using Basic Access Authentication as described in [RFC2617](https://tools.ietf.org/html/rfc2617) +|Digest Authentication| The API authentication relies on using Digest Access Authentication as described in [RFC2617](https://tools.ietf.org/html/rfc2617) +|Pass Through| Headers or query parameters are passed through to the API based on a defined mapping. +|x-{other}| The API authentication relies on another authentication method. -A processing application's developers MAY provide support for these mechanisms. If a mechanism is supported, it MUST conform to the specified standard. +A processing application developer MAY provide support for these mechanisms. If a mechanism is supported, it MUST conform to the specified standard. -Additionally, any security scheme definition may be augmented with a describedBy property, which allows the designer to document the API's security scheme. +Additionally, any security scheme definition may be augmented with a describedBy property, which allows the designer to document the API security scheme. ### Security Scheme Declaration -Security scheme is declared as follows: +The security scheme is declared using the following properties: |Property |Description| |:----------|:----------| -| type | The security schemes property MUST be used to specify an API's security mechanisms, including the required settings and the authentication methods that the API supports. one authentication method is allowed if the API supports them. The value MUST be one of the following: OAuth 1.0, OAuth 2.0, Basic Authentication, Digest Authentication, Pass Through, x-<other> +| type | A security schemes property that MUST be used to specify the API security mechanisms, including the required settings and the authentication methods that the API supports. One supported authentication method is allowed. The value MUST be one of the following methods: OAuth 1.0, OAuth 2.0, Basic Authentication, Digest Authentication, Pass Through, x-<other> | displayName? | An alternate, human-friendly name for the security scheme. -| description? | The description MAY be used to describe a security scheme. -| describedBy? | A description of the request components related to Security that are determined by the scheme: the headers, query parameters or responses. As a best practice, even for standard security schemes, API designers SHOULD describe these properties of security schemes. Including the security scheme description completes an API documentation. See explanation about [describedBy](#describedby) for more information. -| settings? | The settings attribute MAY be used to provide security scheme-specific information. The required attributes vary depending on the type of security scheme is being declared. It describes the minimum set of properties which any processing application MUST provide and validate if it chooses to implement the security scheme. Processing applications MAY choose to recognize other properties for things such as token lifetime, preferred cryptographic algorithms, and more. See explanation about [settings](#settings) for more information. +| description? | Information that MAY be used to explain a security scheme. +| [describedBy?](#describedby) | A description of the following security-related request components determined by the scheme: the headers, query parameters, or responses. As a best practice, even for standard security schemes, API designers SHOULD describe these properties of security schemes. Including the security scheme description completes the API documentation. +| settings? | The [settings](#settings) attribute MAY be used to provide security scheme-specific information. -An optional **securitySchemes** property is defined for RAML document root. +An optional **securitySchemes** property is defined for the RAML document root. The value of securitySchemes is an object. Object properties map security scheme names to security scheme declarations. +Each authentication pattern supported by the API must be expressed as a component of the **securitySchemes** property value. -As value it has an object whose properties map security scheme names to security scheme declarations. -Each authentication pattern supported by the API must be expressed as component of **securitySchemes** property value. - -In this example, the Dropbox API supports authentication via OAuth 2.0 and OAuth 1.0: +In this example, the Dropbox API supports authentication using OAuth 2.0 and OAuth 1.0: ```yaml #%RAML 1.0 title: Dropbox API @@ -2330,15 +2328,15 @@ securitySchemes: queryParameters: access_token: description: | - Used to send a valid OAuth 2 access token. Do not use together with - the "Authorization" header + Used to send a valid OAuth 2 access token. Do not use with + the "Authorization" header. type: string responses: 401: description: | Bad or expired token. This can happen if the user or Dropbox - revoked or expired an access token. To fix, you should re- - authenticate the user. + revoked or expired an access token. To fix, re-authenticate + the user. 403: description: | Bad OAuth request (wrong consumer key, bad nonce, expired @@ -2363,21 +2361,21 @@ The value of the **describedBy** property is defined as follows: |Property |Description| |:----------|:----------| -| headers? | Optional array of headers, documenting the possible headers that could be accepted. See section [Headers](#headers) for more information. -| queryParameters? | Query parameters, used by the schema in order to authorize the request. Mutually exclusive with queryString. See section [Query Strings and Query Parameters](#query-strings-and-query-parameters) for more information. -| queryString? | Specifies the query string, used by the schema in order to authorize the request. Mutually exclusive with queryParameters. See section [Query Strings and Query Parameters](#query-strings-and-query-parameters) for more information. -| responses? | Optional array of responses, describing the possible responses that could be sent. See section [Responses](#responses) for more information. -| (<annotationName>)? | Annotations to be applied to this security scheme part. Annotations are any property whose key begins with "(" and ends with ")" and whose name (the part between the beginning and ending parentheses) is a declared annotation name. See section [Annotations](#annotations) for more information. +| headers? | Optional array of [Headers](#headers), documenting the possible headers that could be accepted. +| queryParameters? | Query parameters, used by the schema to authorize the request. Mutually exclusive with [queryString](#query-strings-and-query-parameters). +| queryString? | The query string used by the schema to authorize the request. Mutually exclusive with [queryParameters](#query-strings-and-query-parameters). +| responses? | An optional array of [responses](#responses), representing the possible responses that could be sent. +| (<annotationName>)? | [Annotations](#annotations) to be applied to this part of the security scheme. An annotation is a property having a key that begins with "(" and ends with ")". The text enclosed in parentheses is the annotation name. #### Settings -The settings attribute MAY be used to provide security scheme specific information. The required attributes vary depending on the type of security scheme is being declared. +The settings attribute MAY be used to provide security scheme-specific information. The required attributes vary depending on which type of security scheme is declared. -It describes the minimum set of properties which any processing application MUST provide and validate if it chooses to implement the security scheme. Processing applications MAY choose to recognize other properties for things such as token lifetime, preferred cryptographic algorithms, and more. +The settings attribute describes the minimum set of properties that any processing application MUST provide and validate if it chooses to implement the security scheme. Processing applications MAY choose to recognize other properties for token lifetime, preferred cryptographic algorithms, and other things. ##### OAuth 1.0 -Security schemes of this type have specific settings object: +Security schemes of this type have the following properties: |Property |Description | |:--------|:------------| @@ -2385,7 +2383,7 @@ Security schemes of this type have specific settings object: |authorizationUri| The URI of the *Resource Owner Authorization endpoint* as defined in [RFC5849 Section 2.2](https://tools.ietf.org/html/rfc5849#section-2.2) |tokenCredentialsUri| The URI of the *Token Request endpoint* as defined in [RFC5849 Section 2.3](https://tools.ietf.org/html/rfc5849#section-2.3) -OAuth 1.0 authentication follows the standard described in [RFC5849](https://tools.ietf.org/html/rfc5849). The following is an example: +OAuth 1.0 authentication follows the standard described in [RFC5849](https://tools.ietf.org/html/rfc5849). The following example shows how to set OAuth 1.0 properties: ```yaml #%RAML 1.0 @@ -2405,16 +2403,16 @@ securitySchemes: ##### OAuth 2.0 -Security schemes of this type has specific settings object: +Security schemes of this type have the following properties: |Property |Description | |:--------|:------------| |authorizationUri| The URI of the *Authorization Endpoint* as defined in [RFC6749 Section 3.1](https://tools.ietf.org/html/rfc6749#section-3.1) |accessTokenUri| The URI of the *Token Endpoint* as defined in [RFC6749 Section 3.2](https://tools.ietf.org/html/rfc6749#section-3.2) -|authorizationGrants| A list of the Authorization grants supported by the API As defined in RFC6749 Sections [4.1](https://tools.ietf.org/html/rfc6749#section-4.1), [4.2](https://tools.ietf.org/html/rfc6749#section-4.2), [4.3](https://tools.ietf.org/html/rfc6749#section-4.3) and [4.4](https://tools.ietf.org/html/rfc6749#section-4.4), can be any of: code, token, owner or credentials. +|authorizationGrants| A list of the authorization grants supported by the API as defined in RFC6749 Sections [4.1](https://tools.ietf.org/html/rfc6749#section-4.1), [4.2](https://tools.ietf.org/html/rfc6749#section-4.2), [4.3](https://tools.ietf.org/html/rfc6749#section-4.3) and [4.4](https://tools.ietf.org/html/rfc6749#section-4.4), which can be any of the following grants: code, token, owner, or credentials. |scopes| A list of scopes supported by the API as defined in [RFC6749 Section 3.3](https://tools.ietf.org/html/rfc6749#section-3.3) -OAuth 2.0 authentication follows the standard described in [RFC6749](https://tools.ietf.org/html/rfc6749). The following is an example: +OAuth 2.0 authentication follows the standard described in [RFC6749](https://tools.ietf.org/html/rfc6749). The following example shows how to set OAuth 2.0 properties: ```yaml #%RAML 1.0 @@ -2436,15 +2434,15 @@ securitySchemes: queryParameters: access_token: description: | - Used to send a valid OAuth 2 access token. Do not use together with - the "Authorization" header + Used to send a valid OAuth 2 access token. Do not use with + the "Authorization" header. type: string responses: 401: description: | Bad or expired token. This can happen if the user or Dropbox - revoked or expired an access token. To fix, you should re- - authenticate the user. + revoked or expired an access token. To fix, re-authenticate + the user. 403: description: | Bad OAuth request (wrong consumer key, bad nonce, expired @@ -2489,7 +2487,7 @@ securitySchemes: ##### Pass Through -Pass Through authentication does not have any specific settings defined and the implementation is known to RAML. One MUST provide a value for every header or queryParameter defined in describedBy, and passed along with the request without modification. The following is an example: +Pass through authentication does not have any specific settings defined and the implementation is known to RAML. You MUST provide a value for every header or queryParameter defined in describedBy and passed along with the request without modification. The following example shows how to provide these values: ```yaml #%RAML 1.0 @@ -2512,7 +2510,7 @@ securitySchemes: ##### x-<other> -x-<other> authentication methods do not have any specific settings defined, as their implementation is unknown as a standard for RAML. These security schemes may only include a description and a describedBy section, to allow documentation of the intended use of the security scheme. The following is an example: +x-<other> authentication methods do not have any specific settings defined, as the implementation of these methods is unknown as a standard to RAML. These security schemes might include only the description and describedBy sections to allow documentation of the intended use of the security scheme. The following example shows such a security scheme: ```yaml #%RAML 1.0 @@ -2539,10 +2537,9 @@ securitySchemes: #### Applying Security Schemes -The **securedBy** attribute of RAML document root may be used to apply security schemes to every method of API. This specifies that all methods in the API (unless they have their own securedBy attribute) can be authenticated by any mentioned security scheme. +The **securedBy** attribute in the RAML document root can apply security schemes to every method of the API. All API methods, except those having their own securedBy attribute, can be authenticated by any of the specified security schemes. -Applying a security scheme to a method overrides whichever security scheme has been applied to the API as whole. -To indicate that the method is protected using a specific security scheme, the method MUST be defined by using the **securedBy** attribute. +Applying a security scheme to a method overrides any security scheme applied to the API as a whole. To indicate that a method is protected using a specific security scheme, the method MUST be defined by using the **securedBy** attribute. The value assigned to the securedBy attribute MUST be a list of any of the security schemes previously defined in the **securitySchemes** property of RAML document root. @@ -2560,7 +2557,7 @@ securitySchemes: securedBy: [oauth_2_0, oauth_1_0] ``` -To indicate that the method may be called without applying any security scheme, the method may be provided with securedBy attribute containing null as array component. +A securedBy attribute containing null as the array component indicates the method can be called without applying any security scheme. ```yaml #%RAML 1.0 @@ -2574,13 +2571,13 @@ securitySchemes: securedBy: [null, oauth_2_0] ``` -A resource can also be applied a list of security schemes using the **securedBy** attribute. This specifies that all methods of this particular resource (unless they have their own securedBy attribute) can be authenticated by any mentioned security scheme. Value of resources attribute overrides that of the root attribute. Security Schemes applied to a resource MUST NOT incorporate nested resources; they do not apply to its existing nested resources. +The **securedBy** attribute can also apply a list of security schemes to a resource. All resource methods, except those having their own securedBy attribute, can be authenticated by any of the specified security schemes. The value of the resources attribute overrides that of the root attribute. Security schemes applied to a resource MUST NOT incorporate nested resources; security schemes do not apply to existing nested resources. -Applying a security scheme to a method overrides security schemes applied to the API and resources having the method as sibling. +Applying a security scheme to a method overrides security schemes applied to the API and to resources having the method as a sibling. If the processing application supports custom properties, custom parameters can be provided to the security scheme at the moment of inclusion in a method. -In the following example, the parameter **scopes** is being assigned: +The following example assigns a value to the parameter **scopes**: ```yaml #%RAML 1.0 @@ -2594,7 +2591,7 @@ securitySchemes: securedBy: [null, oauth_2_0: { scopes: [ ADMINISTRATOR ] } ] ``` -The list of parameters that must and may be provided to the security scheme is specified by the security scheme type. +The list of required and optional parameters to be provided to the security scheme is specified by the security scheme type. ## Annotations From 0b021544efb509df8da592428ce9b44e8f87f682 Mon Sep 17 00:00:00 2001 From: krishahn Date: Tue, 26 Apr 2016 14:39:33 -0700 Subject: [PATCH 198/241] API-supported --- versions/raml-10/raml-10.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/versions/raml-10/raml-10.md b/versions/raml-10/raml-10.md index 112b6c04..9ae49e9b 100644 --- a/versions/raml-10/raml-10.md +++ b/versions/raml-10/raml-10.md @@ -2298,13 +2298,13 @@ The security scheme is declared using the following properties: |Property |Description| |:----------|:----------| -| type | A security schemes property that MUST be used to specify the API security mechanisms, including the required settings and the authentication methods that the API supports. One supported authentication method is allowed. The value MUST be one of the following methods: OAuth 1.0, OAuth 2.0, Basic Authentication, Digest Authentication, Pass Through, x-<other> +| type | The security schemes property that MUST be used to specify the API security mechanisms, including the required settings and the authentication methods that the API supports. One API-supported authentication method is allowed. The value MUST be one of the following methods: OAuth 1.0, OAuth 2.0, Basic Authentication, Digest Authentication, Pass Through, x-<other> | displayName? | An alternate, human-friendly name for the security scheme. -| description? | Information that MAY be used to explain a security scheme. +| description? | Information that MAY be used to describe a security scheme. | [describedBy?](#describedby) | A description of the following security-related request components determined by the scheme: the headers, query parameters, or responses. As a best practice, even for standard security schemes, API designers SHOULD describe these properties of security schemes. Including the security scheme description completes the API documentation. | settings? | The [settings](#settings) attribute MAY be used to provide security scheme-specific information. -An optional **securitySchemes** property is defined for the RAML document root. The value of securitySchemes is an object. Object properties map security scheme names to security scheme declarations. +An optional **securitySchemes** property is defined for the RAML document root. The value of securitySchemes is an object having properties that map security scheme names to security scheme declarations. Each authentication pattern supported by the API must be expressed as a component of the **securitySchemes** property value. In this example, the Dropbox API supports authentication using OAuth 2.0 and OAuth 1.0: From 901fc3d8ce81c4df51b115d712466472052376fa Mon Sep 17 00:00:00 2001 From: krishahn Date: Tue, 26 Apr 2016 20:48:14 -0700 Subject: [PATCH 199/241] copyedit Annotations section and subsections --- versions/raml-10/raml-10.md | 52 +++++++++++++++++++------------------ 1 file changed, 27 insertions(+), 25 deletions(-) diff --git a/versions/raml-10/raml-10.md b/versions/raml-10/raml-10.md index 7255c169..e4e4dd17 100644 --- a/versions/raml-10/raml-10.md +++ b/versions/raml-10/raml-10.md @@ -2598,11 +2598,11 @@ The list of parameters that must and may be provided to the security scheme is s ## Annotations -Annotations provide a mechanism to extend the API specification with metadata beyond the metadata already defined in this RAML 1.0 specification. Annotations can also be regarded as a mechanism to add properties to the built-in RAML properties in certain locations within the RAML specification. Processors MAY support certain annotations to add additional specificity to the API description, enable tooling such as testing, support API repositories and API discovery, and so on. Processors MAY ignore any and all annotations. +Annotations provide a mechanism to extend the API specification with metadata beyond the metadata already defined in this RAML 1.0 specification. Annotations can also be used to add properties to the built-in RAML properties in certain locations within the RAML specification. Processors MAY support certain annotations to add additional specificity to the API description, enable tooling such as testing, support API repositories and API discovery, and so on. Processors MAY ignore any and all annotations. -Annotations used in an API specification MUST be declared in a root-level annotationTypes property. Annotations can have values, which are defined and constrained in annotation type declarations. Processors can then rely on the declarations to ensure annotation values are as expected. +Annotations used in an API specification MUST be declared in a root-level annotationTypes property. Annotations can have values, which are defined and constrained in annotation type declarations. Processors can then rely on the declarations to ensure annotation values meet expectations. -The following is an example of various annotation type declarations and the application of the annotations to an API definition. +The following example shows various annotation type declarations and the application of the annotations to an API definition. ```yaml #%RAML 1.0 @@ -2612,8 +2612,8 @@ annotationTypes: experimental: feedbackRequested: testHarness: - type: string # This line may be omitted as it's the default type - badge: # This annotation type, too, allows string values + type: string # This line can be omitted as it's the default type + badge: # This annotation type allows string values, too clearanceLevel: properties: level: @@ -2638,33 +2638,33 @@ annotationTypes: 200: ``` -Annotations applied to a data type are not inherited when that data type is inherited. However, processors SHOULD make the information about the annotations in the data type hierarchy available. Annotations applied to, or applied within, a resource type or trait are also applied to the resource type or resource or method that inherits it. In particular, if a trait is applied to a resource type or resource, all annotations on or within that trait are applied implicitly to all methods of that resource. If the inheriting resource type or resource or method directly (explicitly) apply an annotation of a given type, then this annotation overrides all applications of that annotation type which would otherwise have been inherited and implicitly applied. In particular, if a trait is applied to a resource type or resource, and the resource type or resource apply an annotation of some type, then any and all applications of annotations of that type to that trait are overridden. +Annotations applied to a data type are not inherited when that data type is inherited. However, processors SHOULD make the information about the annotations in the data type hierarchy available. Annotations applied to, or within, a resource type or trait are also applied to the resource type, resource, or method that inherits the resource type or trait. In particular, if a trait is applied to a resource type or resource, all annotations on or within that trait are applied implicitly to all methods of that resource. If the inheriting resource type, resource, or method explicitly applies an annotation of a given type, then this annotation overrides all applications of that annotation type which would otherwise have been inherited and implicitly applied. In particular, if a trait is applied to a resource type or resource, and the resource type or resource applies an annotation of some type, then any and all applications of annotations of that type to that trait are overridden. ### Declaring Annotation Types -Annotation types are declared using the OPTIONAL root-level **annotationTypes** property. The value of the annotationsType property is an object whose keys define annotation type names, also referred to as annotations, and whose values are objects called annotation type declarations. An annotation type declaration has the same syntax as a data type declaration, and its facets have the same syntax as the corresponding ones for data types, but with the addition of the allowedTargets facet. Just as a data type declaration constrains the value of a URI parameter, query parameter, header, or body of that type, so an annotation type declaration constrains the value of an annotation of that type. The allowedTargets facet restricts at which kinds of locations the annotation may be applied. Annotation types, like data types, may extend other data types, but annotation types may not themselves be extended nor used anywhere data types may be used. +Annotation types are declared using the OPTIONAL root-level **annotationTypes** property. The value of the annotationsType property is an object whose keys define annotation type names, also referred to as annotations, and whose values are objects called annotation type declarations. An annotation type declaration has the same syntax as a data type declaration, and its facets have the same syntax as the corresponding ones for data types, but with the addition of the allowedTargets facet. An annotation type declaration constrains the value of an annotation of that type just as a data type declaration constrains the value of a URI parameter, query parameter, header, or body of that type. The allowedTargets facet restricts the kinds of locations where the annotation can be applied. Annotation types, like data types, can extend other data types, but annotation types themselves can neither be extended nor used anywhere data types can be used. |Property |Description | |:--------|:------------| -| displayName? | The displayName attribute specifies the $self's display name. It is a friendly name used only for display or documentation purposes. If displayName is not specified, it defaults to the element's key (the name of the property itself). -| description? | The description attribute describes the intended use or meaning of an annotation. Its value is a string and MAY be formatted using [markdown](#markdown). -| (<annotationName>)? | Annotations to be applied to this annotation type. Annotations are any property whose key begins with “(“ and ends with “)” and whose name (the part between the beginning and ending parentheses) is a declared annotation name. See section [Annotations](#annotations) for more information. -| allowedTargets? | Restrictions on where annotations of this type can be applied. If this property is specified, annotations of this type may only be applied on a property corresponding to one of the target names specified as the value of this property. Value MUST be one or more of the options described in table [Annotation Target Location](#annotation-target-location). +| displayName? | The display name of $self. A friendly name used only for display or documentation purposes. The default is the element key, the name of the property itself. +| description? | The intended use or meaning of an annotation. A string that MAY be formatted using [markdown](#markdown). +| (<annotationName>)? | [Annotations](#annotations) to be applied to this annotation type. An annotation is a property having a key that begins with "(" and ends with ")". The text enclosed in parentheses is the annotation name. +| allowedTargets? | The locations to which annotations are restricted. If this property is specified, annotations of this type may only be applied on a property corresponding to one of the locations. The value MUST be one or more of the options described in the [Target Locations](#annotation-target-location). -If an annotation type declaration specifies neither a type facet nor a properties facet, then it defaults to a type of string. +If an annotation type declaration specifies neither a type facet nor a properties facet, the default annotationName type is string. All annotations used in an API specification MUST be declared in its annotationTypes property. Any value of an annotation MUST be valid according to its annotation type. -If the allowedTargets property is not present, then the annotation may be applied in any of the target locations listed in the Target Locations table below. If the allowedTargets property is present, it restricts where the annotation may be applied, as described in the section below. +If the allowedTargets property is not present, the annotation can be applied in any of the target locations listed in the Target Locations table. If the allowedTargets property is present, it restricts where the annotation can be applied, as described in [Annotation Targets](#annotation-targets). ### Applying Annotations -For an annotation to be applied in an API specification, the annotation MUST be declared in an annotation type. +To be applied in an API specification, the annotation MUST be declared in an annotation type. -A declared annotation may be applied to an object in the specification by adding a property on that object whose key is the name of the annotation type enclosed in parentheses, and whose value is called an annotation value and MUST be valid according to the corresponding annotation type. +A declared annotation can be applied to an object in the specification by adding a property on that object whose key is the name of the annotation type enclosed in parentheses. The annotation value MUST be valid according to the corresponding annotation type. -The example below, a small subset of the previous example, shows an explicit declaration and use of a testHarness annotation whose value should be a string. +The example below, a small subset of the previous example, shows an explicit declaration and use of a testHarness annotation that should be a string value. ```yaml #%RAML 1.0 @@ -2677,7 +2677,7 @@ annotationTypes: (testHarness): usersTest ``` -The following is semantically equivalent but relies on the implicit default declaration of the value type when there is no explicit type declaration. +The following example is semantically equivalent to the previous one, but relies on the implicit, default declaration of the value type when there is no explicit type declaration. ```yaml #%RAML 1.0 @@ -2691,22 +2691,22 @@ annotationTypes: #### Annotating Scalar-valued Nodes -It is often useful to annotate scalar-valued nodes, e.g. `baseUri`. Since annotations are applied as extra key-value pairs to nodes that accept key-value pairs already (i.e. map-valued nodes), they cannot be easily applied to scalar-valued nodes. To apply annotations to any scalar-valued node, a RAML processor MUST also support scalar-valued nodes to be expressed as a map, with the single allowed key `value`, as an alternative to the normal syntax. +It is often useful to annotate scalar-valued nodes, for example `baseUri`. Annotations are typically applied as extra key-value pairs to map-valued nodes that inherently accept key-value pairs. Annotations cannot be easily applied to scalar-valued nodes. To apply annotations to any scalar-valued node, a RAML processor MUST also support scalar-valued nodes expressed as a map that allow a single key `value` as an alternative to the normal syntax. -The example below shows a scalar-valued node which is normally expressed as: +The following example shows a scalar-valued node which is normally expressed as: ```yaml baseUri: http://www.example.com/api ``` -and the alternative map syntax, with `value` as key: +The alternative map syntax with `value` as the key is added to the example: ```yaml baseUri: value: http://www.example.com/api ``` -and then annotations may be applied as usual, e.g.: +Now, annotations can be applied normally, as shown in this example: ```yaml baseUri: @@ -2714,7 +2714,7 @@ baseUri: (redirectable): true ``` -The following is a list of all available scalar-valued nodes supported in RAML: +The following list shows all available scalar-valued nodes supported in RAML: ``` displayName @@ -2755,10 +2755,12 @@ extends #### Annotation Targets -The location within an API specification where annotations may be applied MUST be one of the target locations in the following Target Locations table. The targets are the locations themselves, not sub-properties within the locations; for example, the Method target refers to the method property and not to the method's display name, description, etc. +The location within an API specification where annotations can be applied MUST be one of the target locations in the following Target Locations table. The targets are the locations themselves, not sub-properties within the locations; for example, the Method target refers to the method property, not to the method display name, description, and so on. +**Target Locations** + |Target | Description | |:--------|:------------| | API | The root of a RAML document @@ -2768,13 +2770,13 @@ The location within an API specification where annotations may be applied MUST b | Response | A property of the responses property, whose key is an HTTP status code | RequestBody | The body property of a method | ResponseBody | The body property of a response -| TypeDeclaration | A data type declaration (inline or in a global types collection), header declaration, query parameter declaration, or URI parameter declaration, or property within any of these declarations, where the type property may be used. +| TypeDeclaration | A data type declaration (inline or in a global types collection), header declaration, query parameter declaration, URI parameter declaration, or a property within any of these declarations, where the type property can be used | Example | Either an example or examples property | ResourceType | A resource type property | Trait | A trait property | SecurityScheme | A security scheme declaration | SecuritySchemeSettings | The settings property of a security scheme declaration -| AnnotationType | A property of the annotationTypes property, whose key is a name of an annotation type and whose value describes the annotation. +| AnnotationType | A property of the annotationTypes property, whose key is a name of an annotation type and whose value describes the annotation | Library | The root of a library | Overlay | The root of an overlay | Extension | The root of an extension From 30b8d3d8a29eb42b8e57683b4cc4be3823649ac9 Mon Sep 17 00:00:00 2001 From: krishahn Date: Tue, 26 Apr 2016 21:30:19 -0700 Subject: [PATCH 200/241] minor edit --- versions/raml-10/raml-10.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/versions/raml-10/raml-10.md b/versions/raml-10/raml-10.md index e4e4dd17..912f7cb9 100644 --- a/versions/raml-10/raml-10.md +++ b/versions/raml-10/raml-10.md @@ -2649,7 +2649,7 @@ Annotation types are declared using the OPTIONAL root-level **annotationTypes** | displayName? | The display name of $self. A friendly name used only for display or documentation purposes. The default is the element key, the name of the property itself. | description? | The intended use or meaning of an annotation. A string that MAY be formatted using [markdown](#markdown). | (<annotationName>)? | [Annotations](#annotations) to be applied to this annotation type. An annotation is a property having a key that begins with "(" and ends with ")". The text enclosed in parentheses is the annotation name. -| allowedTargets? | The locations to which annotations are restricted. If this property is specified, annotations of this type may only be applied on a property corresponding to one of the locations. The value MUST be one or more of the options described in the [Target Locations](#annotation-target-location). +| allowedTargets? | The locations to which annotations are restricted. If this property is specified, annotations of this type may be applied only on a property corresponding to one of the locations. The value MUST be one or more of the options described in the [Target Locations](#annotation-target-location). If an annotation type declaration specifies neither a type facet nor a properties facet, the default annotationName type is string. From 9b95a83c4e909bb69f80b29ce59cbd65b38d39b2 Mon Sep 17 00:00:00 2001 From: Christian Vogel Date: Wed, 27 Apr 2016 13:37:09 +0100 Subject: [PATCH 201/241] removed from annotation type display name description --- versions/raml-10/raml-10.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/versions/raml-10/raml-10.md b/versions/raml-10/raml-10.md index 912f7cb9..9a11bccb 100644 --- a/versions/raml-10/raml-10.md +++ b/versions/raml-10/raml-10.md @@ -2646,7 +2646,7 @@ Annotation types are declared using the OPTIONAL root-level **annotationTypes** |Property |Description | |:--------|:------------| -| displayName? | The display name of $self. A friendly name used only for display or documentation purposes. The default is the element key, the name of the property itself. +| displayName? | A friendly name used only for display or documentation purposes. The default is the element key, the name of the property itself. | description? | The intended use or meaning of an annotation. A string that MAY be formatted using [markdown](#markdown). | (<annotationName>)? | [Annotations](#annotations) to be applied to this annotation type. An annotation is a property having a key that begins with "(" and ends with ")". The text enclosed in parentheses is the annotation name. | allowedTargets? | The locations to which annotations are restricted. If this property is specified, annotations of this type may be applied only on a property corresponding to one of the locations. The value MUST be one or more of the options described in the [Target Locations](#annotation-target-location). From a1a4b083f0a7eb1996f1d2274d4d6c89d6b8b02d Mon Sep 17 00:00:00 2001 From: Christian Vogel Date: Wed, 27 Apr 2016 13:47:26 +0100 Subject: [PATCH 202/241] call out that you can't inherit from different kind of primitive types --- versions/raml-10/raml-10.md | 10 ++++++---- 1 file changed, 6 insertions(+), 4 deletions(-) diff --git a/versions/raml-10/raml-10.md b/versions/raml-10/raml-10.md index 20156a87..e328a08d 100644 --- a/versions/raml-10/raml-10.md +++ b/versions/raml-10/raml-10.md @@ -1245,7 +1245,9 @@ types: In the example above, the type `Teacher` inherits all restrictions from `Person` and `Employee`. -Multiple inheritance is allowed only if the sub-type is still a valid type declaration after inheriting all restrictions from its parent types. For example, the type `Number3` is valid: +Multiple inheritance is allowed only if the sub-type is still a valid type declaration after inheriting all restrictions from its parent types. Also, it is not allowed to inherit from different kind of primitive types, for example `[ number, string ]`. + +In the following example, the sub-type `Number3` is fully valid: ```yaml types: @@ -1271,7 +1273,7 @@ types: Number3: [ Number1, Number2] # invalid, maximum value cannot be less than minimum value ``` -If a sub-type inherits properties having the same name from at least two of its parent types, the sub-type keeps all restrictions applied to those properties with two exceptions: 1) a "pattern" facet when a parent type already declares a "pattern" facet 2) a user-defined facet when another user-defined facet has the same value. In these cases, an invalid type declaration occurs. +If a sub-type inherits properties having the same name from at least two of its parent types, the sub-type keeps all restrictions applied to those properties with two exceptions: 1) a "pattern" facet when a parent type already declares a "pattern" facet 2) a user-defined facet when another user-defined facet has the same value. In these cases, an invalid type declaration occurs. ### Inline Type Declarations @@ -2327,7 +2329,7 @@ The security scheme is declared using the following properties: | displayName? | An alternate, human-friendly name for the security scheme. | description? | Information that MAY be used to describe a security scheme. | [describedBy?](#describedby) | A description of the following security-related request components determined by the scheme: the headers, query parameters, or responses. As a best practice, even for standard security schemes, API designers SHOULD describe these properties of security schemes. Including the security scheme description completes the API documentation. -| settings? | The [settings](#settings) attribute MAY be used to provide security scheme-specific information. +| settings? | The [settings](#settings) attribute MAY be used to provide security scheme-specific information. An optional **securitySchemes** property is defined for the RAML document root. The value of securitySchemes is an object having properties that map security scheme names to security scheme declarations. Each authentication pattern supported by the API must be expressed as a component of the **securitySchemes** property value. @@ -2386,7 +2388,7 @@ The value of the **describedBy** property is defined as follows: |Property |Description| |:----------|:----------| -| headers? | Optional array of [Headers](#headers), documenting the possible headers that could be accepted. +| headers? | Optional array of [Headers](#headers), documenting the possible headers that could be accepted. | queryParameters? | Query parameters, used by the schema to authorize the request. Mutually exclusive with [queryString](#query-strings-and-query-parameters). | queryString? | The query string used by the schema to authorize the request. Mutually exclusive with [queryParameters](#query-strings-and-query-parameters). | responses? | An optional array of [responses](#responses), representing the possible responses that could be sent. From 30d79bd319f6b603abce9eedb7d221cdaf461e6f Mon Sep 17 00:00:00 2001 From: krishahn Date: Wed, 27 Apr 2016 11:37:42 -0700 Subject: [PATCH 203/241] copyedit Includes and subsections --- versions/raml-10/raml-10.md | 59 ++++++++++++++++++------------------- 1 file changed, 29 insertions(+), 30 deletions(-) diff --git a/versions/raml-10/raml-10.md b/versions/raml-10/raml-10.md index 98d5685b..b683a24d 100644 --- a/versions/raml-10/raml-10.md +++ b/versions/raml-10/raml-10.md @@ -2810,7 +2810,7 @@ types: ## Modularization -RAML provides several mechanisms to help modularize your API specification and specifications ecosystem: +RAML provides several mechanisms to help modularize the ecosystem of an API specification: * Includes * Libraries * Overlays @@ -2818,9 +2818,9 @@ RAML provides several mechanisms to help modularize your API specification and s ### Includes -RAML processors MUST support the OPTIONAL **!include** tag, which specifies the inclusion of external files into the API specification. As it is a YAML tag, it starts with an exclamation point ("!"). The location in an API specification where an !include tag may be used MUST be the value of a property, so the result of including the file specified by the !include tag is the value of that property. +RAML processors MUST support the OPTIONAL **!include** tag, which specifies the inclusion of external files into the API specification. Being a YAML tag, the exclamation point ("!") prefix is required. In an API specification, the !include tag is located only in a property value position. The !include tag MUST be the value of a property, which assigns the contents of the file named by the !include tag to the value of the property. -In the following example, the set of types to be used elsewhere in the RAML specification is retrieved from a file called myTypes.raml and used as the value of the types property in the RAML specification. +In the following example, the set of types to be used in the API specification is retrieved from a file called myTypes.raml and used as the value of the types property. ```yaml #%RAML 1.0 @@ -2828,39 +2828,38 @@ title: My API with Types types: !include myTypes.raml ``` -The !include tag accepts a single argument, the location of the content to be included, that MUST be specified explicitly. Its value MUST be one of the following: +The !include tag accepts a single argument, the location of the content to be included, that MUST be specified explicitly. The value of the argument MUST be a path or URL as described in the following table: |Argument | Description | Examples | |:--------|:------------|:---------| -| absolute path | A path that begins with a single slash ("/") and is to be interpreted relative to the root RAML file's location. | /traits/pageable.raml -| relative path | A path that does not begin with a single slash ("/") nor is a URL, and is to be interpreted relative to the including file's location. | description.md
      ../traits/pageable.raml +| absolute path | A path that begins with a single slash ("/") and is interpreted relative to the root RAML file location. | /traits/pageable.raml +| relative path | A path that neither begins with a single slash ("/") nor constitutes a URL, and is interpreted relative to the location of the included file. | description.md
      ../traits/pageable.raml | URL | An absolute URL | http://dev.domain.com/api/patterns/traits.raml -To simplify API definition, and because the included file's parsing context is not shared between the included file and its parent, an included file SHALL NOT use a YAML reference to an anchor in a separate file. Likewise, a reference made from a parent file SHALL NOT reference an anchor defined in an included file. +To simplify the API definition, and because the parsing context of the included file is not shared between the file and its parent, an included file SHALL NOT use a YAML reference to an anchor in a separate file. Likewise, a reference made from a parent file SHALL NOT reference an anchor defined in an included file. -The argument of the !include tag must be static: namely, it MUST NOT contain any resource type parameters or trait parameters. +The !include tag argument must be static: namely, it MUST NOT contain any resource type parameters or trait parameters. #### Typed Fragments -A file to be included MAY begin with a RAML fragment identifier line, which consists of the text _#%RAML_ followed by a single space followed by the text 1.0, followed by a single space followed by one of the following fragment identifiers: +A file to be included MAY begin with a RAML fragment identifier line, which consists of the text _#%RAML_ followed left-to-right by a single space, the text 1.0, a single space, and one of the following fragment identifiers: -|Fragment | Description | -|:--------|:------------| -| DocumentationItem | An item in the collection of items that is the value of the root-level documentation property; see the section on [User Documentation](#user-documentation). -| DataType | A data type declaration, where the type property may be used; see the section on [Types](#types) -| NamedExample | A property of the examples property, whose key is a name of an example and whose value describes the example; see the section on [Examples](#defining-examples-in-raml) -| ResourceType | A single resource type declaration; see the section on [Resource Types and Traits](#resource-types-and-traits) -| Trait | A single trait declaration; see the section on [Resource Types and Traits](#resource-types-and-traits) -| AnnotationTypeDeclaration | A single annotation type declaration; see the section on [Annotations](#annotations) -| Library | A RAML library; see the section on [Libraries](#libraries). -| Overlay | An overlay file; see the section on [Overlays](#overlays). -| Extension | An extension file; see the section on [Extensions](#extensions). -| SecurityScheme | A definition of a security scheme; see section on [Security Schemes](#security-schemes) - -If a file begins with a RAML fragment identifier line, and the fragment identifier is neither Library nor Overlay nor Extension, the contents of the file after removal of the RAML fragment identifier line MUST be valid structurally according to the corresponding section of this RAML specification. For example, a RAML file beginning with `#%RAML 1.0 Trait` must have the structure of a RAML trait declaration as defined in the [specification for traits](#resource-types-and-traits), such that including the file in a location where a trait declaration is called for results in a valid RAML file. +|Fragment Identifier | Description | Relevant RAML Specification Section | +|:-------------------|:------------| :-----------------------------------| +| DocumentationItem | An item in the collection of items that is the value of the root-level documentation property | [User Documentation](#user-documentation) +| DataType | A data type declaration where the type property may be used | [Types](#types) +| NamedExample | A property of the examples property, whose key is a name of an example and whose value describes the example | [Examples](#defining-examples-in-raml) +| ResourceType | A single resource type declaration | [Resource Types and Traits](#resource-types-and-traits) +| Trait | A single trait declaration | [Resource Types and Traits](#resource-types-and-traits) +| AnnotationTypeDeclaration | A single annotation type declaration | [Annotations](#annotations) +| Library | A RAML library | [Libraries](#libraries) +| Overlay | An overlay file | [Overlays](#overlays) +| Extension | An extension file | [Extensions](#extensions) +| SecurityScheme | A definition of a security scheme | [Security Schemes](#security-schemes) -The following example shows a RAML fragment file that defines a resource type, and a file that includes this fragment file. +If a file begins with a RAML fragment identifier line, and the fragment identifier is not Library, Overlay, or Extension, the contents of the file after removal of the RAML fragment identifier line MUST be valid structurally according to the relevant RAML specification. For example, a RAML file beginning with `#%RAML 1.0 Trait` must have the structure of a RAML trait declaration as defined in the [Resource Types and Traits](#resource-types-and-traits) section. Including the file in a correct location for a trait declaration results in a valid RAML file. +The following example shows a RAML fragment file that defines a resource type and a file that includes this fragment file. ```yaml #%RAML 1.0 ResourceType @@ -2868,7 +2867,7 @@ The following example shows a RAML fragment file that defines a resource type, a #This file is located at resourceTypes/collection.raml description: A collection resource -usage: Use this to describe resource that list items +usage: Use this to describe a resource that lists items get: description: Retrieve all items post: @@ -2890,7 +2889,7 @@ resourceTypes: ``` -The resulting API definition is equivalent to the following single document. +The resulting API definition is equivalent to the following single document: ```yaml #%RAML 1.0 @@ -2898,7 +2897,7 @@ title: Products API resourceTypes: collection: description: A collection resource - usage: Use this to describe resource that list items + usage: Use this to describe a resource that lists items get: description: Retrieve all items post: @@ -2914,7 +2913,7 @@ resourceTypes: #### Resolving Includes -When RAML or YAML files are included, RAML parsers MUST not only read the content, but parse it and add the content to the declaring structure as if the content were declared inline. Specifically, if the included file has one of the following media types: +When RAML or YAML files are included, RAML parsers MUST not only read the content, but must also parse it and add the content to the declaring structure as if the content were declared inline. RAML parsers MUST parse the content of the file as RAML content and append the parsed structures to the RAML document node if the included file has a .raml, .yml, or .yaml extension or one of the following media types: * application/raml+yaml * text/yaml @@ -2922,9 +2921,9 @@ When RAML or YAML files are included, RAML parsers MUST not only read the conten * application/yaml * application/x-yaml -or a .raml or .yml or .yaml extension, RAML parsers MUST parse the content the file as RAML content and append the parsed structures to the RAML document's node. Otherwise, the contents of the file will be included as a scalar. +Otherwise, if RAML parsers fail to parse the content and append structures, the contents of the file are included as a scalar. -To simplify RAML definitions, and because the included files parsing context is not shared between the included file and its parent, an included file SHALL NOT use a YAML reference to an anchor in a separate file. Likewise, a reference made from a parent file SHALL NOT reference a structure anchor defined in an included file. +Because the parsing context of the included files is not shared between the included file and its parent, an included file SHALL NOT use a YAML reference to an anchor in a separate file. Likewise, a reference made from a parent file SHALL NOT reference a structure anchor defined in an included file. These rules simplify RAML definitions. In the example below, the API root document includes two files from the patterns folder, one containing resource type declarations and the other containing trait declarations. From 3ba1f43e0aef4976cdee7bd55ddaea9b345f3a45 Mon Sep 17 00:00:00 2001 From: krishahn Date: Wed, 27 Apr 2016 15:11:43 -0700 Subject: [PATCH 204/241] copyedit Libraries section --- versions/raml-10/raml-10.md | 20 ++++++++++---------- 1 file changed, 10 insertions(+), 10 deletions(-) diff --git a/versions/raml-10/raml-10.md b/versions/raml-10/raml-10.md index 98d5685b..4daa4f39 100644 --- a/versions/raml-10/raml-10.md +++ b/versions/raml-10/raml-10.md @@ -2990,14 +2990,14 @@ traits: ### Libraries -RAML libraries are used to combine any collection of data type declarations, resource type declarations, trait declarations, and security scheme declarations into modular, externalized, reusable groups. While libraries are meant to allow definition of common declarations in external documents which are then included where needed, they may also be defined inline. +RAML libraries are used to combine any collection of data type declarations, resource type declarations, trait declarations, and security scheme declarations into modular, externalized, reusable groups. While libraries are intended to define common declarations in external documents, which are then included where needed, libraries can also be defined inline. -A library is an object whose allowed properties are enumerated in the following table. Each is optional. +The following table describes the properties, which are optional, of a library object. |Property | Description | |:--------|:------------| -| types?
      schemas?
      resourceTypes?
      traits?
      securitySchemes?
      annotationTypes?
      (<annotationName>)?
      uses? | The definition of each property is the same as that of the corresponding property in the root of a RAML document. Annotation properties are allowed as in any other RAML document. -| usage | Describes the content or purpose of a specific library. Its value is a string and MAY be formatted using [markdown](#markdown). +| types?
      schemas?
      resourceTypes?
      traits?
      securitySchemes?
      annotationTypes?
      (<annotationName>)?
      uses? | The definition of each property is the same as that of the corresponding property at the root of a RAML document. A library supports annotation properties like any other RAML document. +| usage | Describes the content or purpose of a specific library. The value is a string and MAY be formatted using [markdown](#markdown). The following example shows a simple library as a standalone, reusable RAML fragment document. @@ -3021,17 +3021,17 @@ resourceTypes: is: drm put: is: drm -``` +```user documentation #### Applying Libraries -Any number of libraries may be applied by using the OPTIONAL **uses** property which may ONLY be used at the root of a RAML file (either a root ["master"] RAML file or a RAML fragment file). The value of the uses property is a map of key-value pairs where its keys are treated as library names, or namespaces, and the value MUST be the location of a RAML library file, usually an external RAML library fragment document. +Any number of libraries can be applied by using the OPTIONAL **uses** property ONLY at the root of a ["master"] RAML or RAML fragment file. The value of the uses property is a map of key-value pairs. The keys are treated as library names, or namespaces, and the value MUST be the location of a RAML library file, usually an external RAML library fragment document. -When a library is applied, the data types, resource types, traits, security schemes, and annotation types which it declared are made available in the document in which it was applied, but are referenced via names formed by concatenating the library name followed by a period (".") followed by the name of the data type, resource type, trait, security scheme, or annotation type. In this way the library name defines a namespace for the library's objects within the context in which the library was applied. That means, namespaces defined in a **uses** statement in a specific file are only consumable within that file, i.e. they are only used to disambiguate the included libraries from each other within that file. Therefore, any processor MUST not be permitted to allow any composition of namespaces using "." across multiple libraries. +In the document that applies a library, the data types, resource types, traits, security schemes, and annotation types in the library become available from the document. The assets in the library are referenced from the document using dot notation as follows: concatenate the library name followed by a period ("."), and then the name of the data type, resource type, trait, security scheme, or annotation type. The library name defines a namespace for the library objects within the context that the library is applied. Namespaces defined in a **uses** statement in a specific file are only consumable within that file and serve only to disambiguate the included libraries from each other. Therefore, any processor MUST not allow any composition of namespaces using "." across multiple libraries. -Using **uses** does NOT automatically import the remote library's assets into the local file, but it allows the local file to import those assets by referring to them in its contents: e.g., a RAML type fragment file that uses a library of remote types can then import one of those types by referring to it, and that remote type will be included as if it were defined locally within the RAML type fragment file. +Using **uses** does NOT automatically import the remote library assets into the local file, but the local file can import those assets by referring to the assets from its contents. For example, a RAML type fragment file that uses a library of remote types can import one of those types by referring to it. The remote type is included as if it were defined locally within the RAML type fragment file. -The following examples demonstrate the use of a library in a second library, and the use of that second library in a resource type fragment as well as in RAML API definition. +The following examples demonstrate the use of a library in a second library, a second library in a resource type fragment, and a second library in a RAML API definition. ```yaml #%RAML 1.0 Library @@ -3078,7 +3078,7 @@ get: is: files.drm ``` -The following example is not valid according to the restriction that chaining namespaces is not allowed. +The following example is not valid because chaining namespaces is not allowed. ```yaml #%RAML 1.0 ResourceType From e603be13285db383924940ab05687fd03338c576 Mon Sep 17 00:00:00 2001 From: krishahn Date: Wed, 27 Apr 2016 17:05:56 -0700 Subject: [PATCH 205/241] copyedit Overlays and Extensions section --- versions/raml-10/raml-10.md | 39 +++++++++++++++++++++---------------- 1 file changed, 22 insertions(+), 17 deletions(-) diff --git a/versions/raml-10/raml-10.md b/versions/raml-10/raml-10.md index 98d5685b..f47f9ff4 100644 --- a/versions/raml-10/raml-10.md +++ b/versions/raml-10/raml-10.md @@ -3096,36 +3096,41 @@ get: ### Overlays and Extensions -API definitions may need to be extended in a variety of ways for different needs. Annotations allow for adding metadata beyond that which is standardized in this RAML specification. Another set of needs is satisfied by overlaying standard or non-standard metadata on top of an existing API definition without changing its behavior, for example to specify implementation details or provide a translation of human-oriented documentation into different languages. Yet another set of needs requires extending an API definition by adding to its behavior or overriding certain aspects. RAML provides two mechanisms for doing so: overlays and extensions. +API definitions might need to be extended in a variety of ways for different needs. Annotations extend an API by adding metadata beyond that which is standardized in this RAML specification. Overlays of standard or non-standard metadata on top of an existing API definition can specify implementation details, or provide a translation of human-oriented documentation into different languages, without changing API behavior. Extending an API definition by adding to its behavior, or overriding certain aspects, is another way to satisfy different needs. RAML provides two mechanisms for extending API definitions: overlays and extensions. -Overlays and extensions are RAML documents that add or override properties of a RAML API definition. The first line of an overlay or extension document MUST begin with the text _#%RAML 1.0 Overlay_ or _#%RAML 1.0 Extension_, respectively, followed by nothing but the end of the line. An overlay or extension document MUST contain a root-level `extends` property whose value MUST be the location of a valid RAML API definition, or another overlay or extension; the location is specified equivalently to the location specified in the value of an !include tag (as an absolute or relative path or as a URL). The document specified in the `extends` property is called the master RAML document. +Overlays and extensions are RAML documents that add or override properties of a RAML API definition. The first line of an overlay or extension document MUST begin with the text _#%RAML 1.0 Overlay_ or _#%RAML 1.0 Extension_, respectively, followed by nothing but the end of the line. An overlay or extension document MUST contain a root-level `extends` property whose value MUST be the location of a valid RAML API definition or another overlay or extension; the location specification is an absolute or relative path, or a URL, equivalent to an [!include tag argument](#includes). The document specified in the `extends` property is called the master RAML document. -The remainder of an overlay or extension document follows the same rules as a RAML API definition, but with certain restrictions in case of an overlay, as discussed in section about [Overlays](#overlays). +The remainder of an overlay or extension document follows the same rules as a RAML API definition, but with certain [restrictions](#overlays) in case of an overlay. -To apply an overlay or extension, RAML processors MUST apply the merging algorithm described in the Merging Rules section below to the master RAML document and the extension or overlay, thereby producing a modified API definition; in the case of applying an overlay, the modified API definition is then validated against the master RAML document to adhere to the restrictions on overlays. +To apply an overlay or extension, RAML processors MUST apply the [merging algorithm](#merging-rules) to the master RAML document and the extension or overlay, thereby producing a modified API definition; in the case of applying an overlay, the modified API definition is then validated against the master RAML document to adhere to the restrictions on overlays. -To apply any combination of overlays and/or extensions, all of them must share the same master RAML document; the first is applied to the master RAML document as before, producing a modified API definition, and validating the result in the case of an overlay; then the second overlay or extension is applied to that modified API definition as if the latter were the master RAML document, and again validating the result in the case of an overlay; and so on until the last overlay or extension. All !include tags are resolved before any application of the merging algorithm, the validation of restrictions on overlays occurs after each overlay is applied, and all inheritances (of types, resource types, traits, and annotation types) are applied at the end of the application of all overlays and extensions. +To apply any combination of overlays and/or extensions, all must share the same master RAML document. The application process is: + +1. Apply the first overlay or extension to the master RAML document, producing a modified API definition and validating the result in the case of an overlay. +2. Apply the second overlay or extension to the modified API definition as if the latter were the master RAML document, and again validate the result in the case of an overlay. +3. Repeat the previous step until the last overlay or extension is applied. +4. Resolve all !include tags before any application of the merging algorithm, validate restrictions on overlays after each overlay is applied, and apply all inheritances of types, resource types, traits, and annotation types. #### Overlays -An overlay adds or overrides properties of a RAML API definition while preserving its behavioral, functional aspects. Certain properties of a RAML API definition specify the behavior of an API: its resources, methods, parameters, bodies, responses, etc. These may not be changed by applying an overlay. In contrast, other properties such as descriptions or annotations address concerns beyond the functional interface, such as the human-oriented descriptive documentation in some language, or implementation or verification information for use in automated tools. These may be changed by applying an overlay. +An overlay adds or overrides properties of a RAML API definition while preserving its behavioral, functional aspects. Certain properties of a RAML API definition specify the behavior of an API: its resources, methods, parameters, bodies, responses, and so on. These properties cannot be changed by applying an overlay. In contrast, other properties, such as descriptions or annotations, address concerns beyond the functional interface, such as the human-oriented descriptive documentation in some language, or implementation or verification information for use in automated tools. These properties can be changed by applying an overlay. -Overlays are particularly important for separating interface from implementation, and for enabling separate lifecycles for the behavioral aspects of the API that need to be controlled more tightly as a contract between the API provider and its consumers, versus the human- or implementation-oriented aspects that can evolve at different paces. For example, adding hooks for testing and monitoring tools, appending metadata relevant to a registry of APIs, or or providing updated or translated human documentation can be achieved without changing any aspects of the behavioral aspects of the API, which may be controlled through a more rigorous version and change management process. +Overlays are particularly important for separating interface from implementation. Overlays enable separate lifecycles for the behavioral aspects of the API that need to be controlled tightly, such as a contract between the API provider and its consumers, versus those needing little control, such as the human- or implementation-oriented aspects that can evolve at different paces. For example, adding hooks for testing and monitoring tools, appending metadata relevant to a registry of APIs, or providing updated or translated human documentation can be achieved without changing any aspects of the behavioral aspects of the API. These things can be controlled through a rigorous version and change management process. -While it is difficult to draw a definitive line between the two, for example because some semantics of the API is often captured only in human documentation, RAML does define the specific behavior-invariance restrictions on overlay files which processors MUST follow. Processors may then choose to offer the master API definition as well as its modifications after applying one or more overlays, so the consumer may benefit from all the information available; for example, if overlay files are provided as a means of localizing textual descriptions of resources, methods, and data, the consumer of generated documentation may be offered a choice of which localized overlays to apply. +It is difficult to draw a definitive line between the behavioral and implementation-oriented aspects of the API because, for example, some semantics of the API are often captured only in human documentation. RAML does, however, define the specific behavior-invariance restrictions on overlay files that processors MUST follow. Processors can then choose to offer the master API definition as well as its modifications after applying one or more overlays, so the consumer can benefit from all the information available. For example, if overlay files are provided as a means of localizing textual descriptions of resources, methods, and data, the consumer of generated documentation can be offered a choice of which localized overlays to apply. -The behavior-invariance restrictions of an overlay are defined as follows: after applying the merging algorithm described in the Merging Rules section, and before any inheritances (of types, resource types, traits, and annotation types) are applied, the tree of nodes in the merged document is compared with the tree of nodes in the master RAML document after resolving all !include tags. Any differences MUST only be in properties listed in the following table. +The behavior-invariance restrictions of an overlay are defined as follows: after applying the [merging algorithm](#merging-rules) and before applying any inheritances of types, resource types, traits, and annotation types, the tree of nodes in the merged document is compared with the tree of nodes in the master RAML document after resolving all !include tags. Any differences in the documents MUST be only in the properties listed in the following table. |Property | Allowed differences | |:--------|:------------| -| title
      description
      documentation
      usage
      example | The merged tree may include new properties of this type, or properties with different values than those in the master tree. -| types | In addition to allowed differences described elsewhere in this table, the merged tree may also include new data types. -| annotationTypes | The merged tree may include new annotation types, or new values for existing annotation types, as long as all annotations in the merged API definition validate against the annotation types in the merged tree. -| any annotation property | The merged tree may include new annotations of annotation types declared in the merged tree, or annotations with different values than those in the master tree. -| examples | The merged tree may contain new named examples, or named examples with different values than those in the master tree. -| documentation | The merged tree may contain new items in the array that is the value of the documentation root-level property. To change or remove existing items, the documentation property itself may be overridden in the overlay. - -The following example illustrates a (very) simple RAML definition of a library books API, along with an overlay file that provides a Spanish translation and an overlay file that provides metadata for an API monitoring service. +| title
      description
      documentation
      usage
      example | The merged tree can include new properties of this type or properties with different values from those in the master tree. +| types | In addition to allowed differences described elsewhere in this table, the merged tree can also include new data types. +| annotationTypes | The merged tree can include new annotation types or new values for existing annotation types, as long as all annotations in the merged API definition validate against the annotation types in the merged tree. +| any annotation property | The merged tree can include new annotations of annotation types declared in the merged tree, or annotations with different values from those in the master tree. +| examples | The merged tree can contain new named examples, or named examples with different values from those in the master tree. +| documentation | The merged tree can contain new items in the array that is the value of the documentation root-level property. To change or remove existing items, the documentation property itself can be overridden in the overlay. + +The following example illustrates a very simple RAML definition of a library books API, along with overlay files that provide a Spanish translation and metadata for an API monitoring service. ```yaml #%RAML 1.0 From c47861c0c7ac9f8e2a84d3ed2bd86f3835c7c61c Mon Sep 17 00:00:00 2001 From: krishahn Date: Wed, 27 Apr 2016 20:41:17 -0700 Subject: [PATCH 206/241] copyedit Extensions to References sections --- versions/raml-10/raml-10.md | 44 ++++++++++++++++++------------------- 1 file changed, 22 insertions(+), 22 deletions(-) diff --git a/versions/raml-10/raml-10.md b/versions/raml-10/raml-10.md index 98d5685b..2d858a67 100644 --- a/versions/raml-10/raml-10.md +++ b/versions/raml-10/raml-10.md @@ -3178,9 +3178,9 @@ annotationTypes: #### Extensions -An extension allows extending a RAML API definition by adding to, or modifying, its behavioral (functional) aspects as well as its non-behavioral aspects. This can be useful in separating a core, broadly-available API from layers of functionality available to more restricted audiences, for creating variants of an API for somewhat different purposes, or for specifying instance-specific properties of an API such as its service endpoint (URL) without altering its pure interface definition document. +An extension broadens a RAML API definition by adding to, or modifying, aspects of its behavior and other functionality. An extension can be useful in separating a core, broadly-available API from layers of functionality available to more restricted audiences, for creating variants of an API for somewhat different purposes, or for specifying instance-specific properties of an API, such as its service endpoint (URL) without altering its pure interface definition document. -The following examples build on the examples in the overlays section above, by adding an extension available to admins for adding items (books) to a collection, adding an overlay to provide a translation of the added functionality, and adding an extension that locates a particular service endpoint of the API. +The following examples build on the examples in the previous Overlays section by adding an extension available to admins for adding items (books) to a collection, adding an overlay to provide a translation of the added functionality, and adding an extension that locates a particular service endpoint of the API. ```yaml #%RAML 1.0 Extension @@ -3209,7 +3209,7 @@ baseUri: http://api.piedmont-library.com #### Merging Rules -The algorithm of how exactly an overlay/extension structure is applied to the master is described in this section. +This section describes how an overlay/extension structure is applied to the master. ##### Terminology @@ -3217,9 +3217,9 @@ The algorithm of how exactly an overlay/extension structure is applied to the ma _Object_ is a MAP or a SEQUENCE containing MAPPINGS in terms of YAML. -_Property_ is a MAPPING in terms of YAML, the pair of key and its value. +_Property_ is a MAPPING in terms of YAML, a key and its value pair. -In the following example, "properties" highlighted in yellow is a _Property_ key, and the corresponding _Object_ value is highlighted in green. +In the following example, the yellow "properties" is a _Property_ key, and the corresponding green _Object_ is the value. 

       properties:
@@ -3229,7 +3229,7 @@ In the following example, "properties" highlighted in yellow is a _Property_ key
       description: "some description"
      -In the same example, there is also a "responseParameters" _Property_ key and its _Object_ value colored in green: +In the same example, there is also a green "responseParameters" _Property_ key and its _Object_ value: 
       properties:
@@ -3239,7 +3239,7 @@ In the same example, there is also a "responseParameters" _Property_ key and its
       description: "some description"
      -And while "statusCode", "type" and "description" colored yellow are also properties, their values are not _Objects_: +And while the yellow "statusCode", "type" and "description" are also properties, their values are not _Objects_: 
       properties:
@@ -3249,7 +3249,7 @@ And while "statusCode", "type" and "description" colored yellow are also propert
        description: "some description"
      -In the following sample "FilteredByPrice" and "Paged" are yellow-colored _Properties_ with _Object_ values colored in green. +In the following sample, yellow "FilteredByPrice" and "Paged" are _Properties_ with green _Object_ values. 
       traits:
@@ -3269,7 +3269,7 @@ In the following sample "FilteredByPrice" and "Paged" are yellow-colored _Proper
 
 _Array_ is a SEQUENCE containing SCALARs or SEQUENCE containing MAPs in terms of YAML.
 
-In the following example, the "enum" _Property_ key is highlighted in yellow that has an _Array_ value highlighted blue.
+In the following example, the yellow "enum" _Property_ key has a blue _Array_ value.
 
 
       enum:
@@ -3278,7 +3278,7 @@ In the following example, the "enum" _Property_ key is highlighted in yellow tha
  - Colored
 
      
 
-Another example for an _Array_ definition, a "documentation" _Property_ key has an _Array_ value, which contains two _Objects_ highlighted in green:
+In this example of an _Array_ definition, a "documentation" _Property_ key has an _Array_ value, which contains two green _Objects_:
 
 
       documentation:
@@ -3291,7 +3291,7 @@ Another example for an _Array_ definition, a "documentation" _Property_ key has
 
 ###### Property Types
 
-In the merging algorithm the _Property_ types are referred to as _Property Kind_ which can be one of the following (highlighted in **bold**):
+In the merging algorithm, the _Property_ types are referred to as _Property Kind_, which can be one of the following properties highlighted in **bold**:
 
 **_Object Property_** - a _Property_ having _Object_ as a value.
 
@@ -3344,7 +3344,7 @@ In the following sample "statusCode" and "enum" are simple properties.
 
      
 
 Exceptions:
-* Examples are always _Simple Properties_ despite its ability to have complex YAML samples as values.
+* Examples are always _Simple Properties_ despite the capability to have complex YAML samples as values.
 * Annotations are always _Simple Properties_ despite potentially having a complex node structure.
 * Resource type applications are always _Simple Properties_.
 * Trait applications are always _Simple Properties_.
@@ -3352,9 +3352,9 @@ Exceptions:
 
 ###### Conflicting Properties
 
-Conflicting properties are the properties, which can not coexist in the same Object at the same time.
+Conflicting properties are the properties that cannot coexist in the same Object.
 
-In the following example both "type" and "properties" _Properties_ can coexist with each other, but the "enum" _Property_ cannot coexist with both "type" and "properties".
+In the following example, both "type" and "properties" _Properties_ can coexist, but the "enum" _Property_ cannot coexist with both "type" and "properties".
 
 
       color:
@@ -3397,28 +3397,28 @@ For each **Current Extension Tree Object property** the following is done:
 
 * If the **property** is an _Ignored Property_, continue to process the next property.
 * If the **property** with the same name exists in **Current Target Tree Object**:
-  * If the **property** and the equally named property in **Current Target Tree Object** have different _Property Kind_:
-    * The **property** value in the equally named **Current Target Tree Object** property is replaced with its value from **Current Extension Tree Object** property.
+  * If the **property** and the identically named property in **Current Target Tree Object** have different _Property Kind_:
+    * The **property** value in the identically named **Current Target Tree Object** property is replaced with its value from **Current Extension Tree Object** property.
   * If the **property** is a _Simple Property_
     * If the **property** is a _Single-value Simple Property_,
-      * The **property** value in the equally named **Current Target Tree Object** property is replaced with its value from **Current Extension Tree Object** property.
+      * The **property** value in the identically named **Current Target Tree Object** property is replaced with its value from **Current Extension Tree Object** property.
     * If the **property** is a _Multi-value Simple Property_
-      * The **property** value from **Current Extension Tree Object** property is added to the equally named **Current Target Tree Object** property values if no such value already exists.
+      * The **property** value from **Current Extension Tree Object** property is added to the identically named **Current Target Tree Object** property values if no such value already exists.
   * If the **property** is an _Object Property_:
-    * The same _Merging Algorithm_ is recursively performed for **Current Extension Tree Object** being set to the **property** value, and **Current Target Tree Object** being set to the value of the equally named property in **Current Target Tree Object**.
+    * The same _Merging Algorithm_ is recursively performed for **Current Extension Tree Object** being set to the **property** value, and **Current Target Tree Object** being set to the value of the identically named property in **Current Target Tree Object**.
   * If the **property** is an _Array Property_:
-    * _Objects_ from the property value are added to the equally named **Current Target Tree Object** property value.
+    * _Objects_ from the property value are added to the identically named **Current Target Tree Object** property value.
 * If the **property** with the same name does not exist in **Current Target Tree Object**:
   * All _Conflicting Properties_ are removed from the **Current Target Tree Object**
   * The **property** is added to the **Current Target Tree Object**.
 
 _Target Tree_ is validated.
 
-If the _Extension Tree_ is an Overlay, _Target Tree_ is compared to the _Master Tree_. There MUST NOT be any differences, besides listed in the "Allowed differences" table in section [Overlays](#overlays). Otherwise the process is cancelled.
+If the _Extension Tree_ is an Overlay, _Target Tree_ is compared to the _Master Tree_. There MUST NOT be any differences, other than those listed in the "Allowed differences" table in the [Overlays](#overlays) section. Otherwise the process is cancelled.
 
 _Target Tree_ has its resource types and Traits applied.
 
-_Target Tree_ is being serialized to a document, or returned as the algorithm output.
+_Target Tree_ is being serialized to a document or returned as the algorithm output.
 
 ## References
 

From ada1cd89e807b3043265989db318f79ab52df98a Mon Sep 17 00:00:00 2001
From: krishahn 
Date: Wed, 27 Apr 2016 20:52:25 -0700
Subject: [PATCH 207/241] minor edits

---
 versions/raml-10/raml-10.md | 6 +++---
 1 file changed, 3 insertions(+), 3 deletions(-)

diff --git a/versions/raml-10/raml-10.md b/versions/raml-10/raml-10.md
index 2d858a67..cb3e05b1 100644
--- a/versions/raml-10/raml-10.md
+++ b/versions/raml-10/raml-10.md
@@ -3178,9 +3178,9 @@ annotationTypes:
 
 #### Extensions
 
-An extension broadens a RAML API definition by adding to, or modifying, aspects of its behavior and other functionality. An extension can be useful in separating a core, broadly-available API from layers of functionality available to more restricted audiences, for creating variants of an API for somewhat different purposes, or for specifying instance-specific properties of an API, such as its service endpoint (URL) without altering its pure interface definition document.
+An extension broadens a RAML API definition by adding to, or modifying aspects of its behavior and other functionality. An extension can be useful in separating a core, broadly-available API from layers of functionality available to more restricted audiences, for creating variants of an API for somewhat different purposes, or for specifying instance-specific properties of an API, such as its service endpoint (URL) without altering its pure interface definition document.
 
-The following examples build on the examples in the previous Overlays section by adding an extension available to admins for adding items (books) to a collection, adding an overlay to provide a translation of the added functionality, and adding an extension that locates a particular service endpoint of the API.
+The following examples build on examples in the Overlays section by adding an extension for admins to add book items to a collection, adding an overlay to provide a translation of the added functionality, and adding an extension that locates a particular service endpoint of the API.
 
 ```yaml
 #%RAML 1.0 Extension
@@ -3278,7 +3278,7 @@ In the following example, the yellow "enum" _Property_ key has a blue _Array_ va
  - Colored
 
      
 
-In this example of an _Array_ definition, a "documentation" _Property_ key has an _Array_ value, which contains two green _Objects_:
+In this example of an _Array_ definition, a "documentation" _Property_ key has an _Array_ value that contains two green _Objects_:
 
 
       documentation:

From 030acf85ce82d2029488c94b0c88b1e939a4b437 Mon Sep 17 00:00:00 2001
From: Christian Vogel 
Date: Thu, 28 Apr 2016 09:39:37 +0100
Subject: [PATCH 208/241] modified query parameter text and how validation is
 handled

---
 versions/raml-10/raml-10.md | 6 +++---
 1 file changed, 3 insertions(+), 3 deletions(-)

diff --git a/versions/raml-10/raml-10.md b/versions/raml-10/raml-10.md
index 98d5685b..34b87df7 100644
--- a/versions/raml-10/raml-10.md
+++ b/versions/raml-10/raml-10.md
@@ -1787,7 +1787,7 @@ If a query parameter declaration specifies an array type for the value of the qu
 
 If a query parameter declaration specifies a non-array type for the value of the query parameter, or doesn't specify a type (equivalent to specifying a string type), processors MUST disallow multiple instances of that query parameter in the request.
 
-Processors MUST default to treating the format of the query parameter value as JSON in applying the type to instances of a query parameter if a query parameter definition specifies the value of a query parameter as any of the following types: an object type, a union of non-scalar types, or an array type if the underlying type of the array is an object type or union of non-scalar types.
+RAML does not define validation when a query parameter declaration specifies any of the following types for the value of the query parameter: an object type, a union of non-scalar types, or an array type if the underlying type of the array is an object type or union of non-scalar types. Processors MAY default to treating the format of the query parameter value as JSON in applying the type to instances of that query parameter, or they MAY allow other treatments based on annotations.
 
 The standard serialization rules for types MUST be invoked in applying the type to instances of a query parameter if the query parameter definition specifies the value of the query parameter as any of the following types: a non-string scalar type, a union of non-string scalar types, or an array type if the underlying type of the array is a non-string scalar type or union of non-string scalar types.
 
@@ -2302,7 +2302,7 @@ The security scheme is declared using the following properties:
 | displayName? | An alternate, human-friendly name for the security scheme.
 | description? | Information that MAY be used to describe a security scheme.
 | [describedBy?](#describedby) | A description of the following security-related request components determined by the scheme: the headers, query parameters, or responses. As a best practice, even for standard security schemes, API designers SHOULD describe these properties of security schemes. Including the security scheme description completes the API documentation.
-| settings? | The [settings](#settings) attribute MAY be used to provide security scheme-specific information. 
+| settings? | The [settings](#settings) attribute MAY be used to provide security scheme-specific information.
 
 An optional **securitySchemes** property is defined for the RAML document root. The value of securitySchemes is an object having properties that map security scheme names to security scheme declarations.
 Each authentication pattern supported by the API must be expressed as a component of the **securitySchemes** property value.
@@ -2361,7 +2361,7 @@ The value of the **describedBy** property is defined as follows:
 
 |Property   |Description|
 |:----------|:----------|
-| headers? | Optional array of [Headers](#headers), documenting the possible headers that could be accepted. 
+| headers? | Optional array of [Headers](#headers), documenting the possible headers that could be accepted.
 | queryParameters? | Query parameters, used by the schema to authorize the request. Mutually exclusive with [queryString](#query-strings-and-query-parameters).
 | queryString? | The query string used by the schema to authorize the request. Mutually exclusive with [queryParameters](#query-strings-and-query-parameters).
 | responses? | An optional array of [responses](#responses), representing the possible responses that could be sent.

From dbd18bde447db8c74149adaaf69f8037f5ba9d3a Mon Sep 17 00:00:00 2001
From: Christian Vogel 
Date: Thu, 28 Apr 2016 12:19:49 +0100
Subject: [PATCH 209/241] updated examples and fixed some array vs single
 string bugs

---
 versions/raml-10/raml-10.md | 12 ++++++------
 1 file changed, 6 insertions(+), 6 deletions(-)

diff --git a/versions/raml-10/raml-10.md b/versions/raml-10/raml-10.md
index 4daa4f39..1ff45081 100644
--- a/versions/raml-10/raml-10.md
+++ b/versions/raml-10/raml-10.md
@@ -3018,9 +3018,9 @@ traits:
 resourceTypes:
   file:
     get:
-      is: drm
+      is: [ drm ]
     put:
-      is: drm
+      is: [ drm ]
 ```user documentation
 
 #### Applying Libraries
@@ -3058,14 +3058,14 @@ traits:
 resourceTypes:
   file:
     get:
-      is: drm
+      is: [ drm ]
       responses:
         201:
           body:
             application/json:
               type: file-type.File
     put:
-      is: drm
+      is: [ drm ]
 
 ```
 
@@ -3075,7 +3075,7 @@ resourceTypes:
 uses:
   files: libraries/files.raml
 get:
-  is: files.drm
+  is: [ files.drm ]
 ```
 
 The following example is not valid because chaining namespaces is not allowed.
@@ -3086,7 +3086,7 @@ The following example is not valid because chaining namespaces is not allowed.
 uses:
   files: libraries/files.raml
 get:
-  is: files.drm
+  is: [ files.drm ]
   responses:
     200:
       body:

From 558563797007609c16579d551a92234c56dd0f23 Mon Sep 17 00:00:00 2001
From: Christian Vogel 
Date: Thu, 28 Apr 2016 12:21:09 +0100
Subject: [PATCH 210/241] removed unrelated text

---
 versions/raml-10/raml-10.md | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/versions/raml-10/raml-10.md b/versions/raml-10/raml-10.md
index 1ff45081..ce13f1f5 100644
--- a/versions/raml-10/raml-10.md
+++ b/versions/raml-10/raml-10.md
@@ -3021,7 +3021,7 @@ resourceTypes:
       is: [ drm ]
     put:
       is: [ drm ]
-```user documentation
+```
 
 #### Applying Libraries
 

From 9c981e19718768ea641bc9f040dc173d5bbacf5a Mon Sep 17 00:00:00 2001
From: Christian Vogel 
Date: Fri, 29 Apr 2016 10:22:52 +0100
Subject: [PATCH 211/241] added link in multiple inheritance section to an
 example in union type section

---
 versions/raml-10/raml-10.md | 3 +++
 1 file changed, 3 insertions(+)

diff --git a/versions/raml-10/raml-10.md b/versions/raml-10/raml-10.md
index e328a08d..165cd6cf 100644
--- a/versions/raml-10/raml-10.md
+++ b/versions/raml-10/raml-10.md
@@ -1134,6 +1134,7 @@ CatOrDog: # follows restrictions applied to the type 'Cat'
   color: "brown"
 ```
 
+
 Imagine a more complex example of a union type used in a multiple inheritance type expression:
 
 ```yaml
@@ -1273,6 +1274,8 @@ types:
   Number3: [ Number1, Number2] # invalid, maximum value cannot be less than minimum value
 ```
 
+Section [union types](#union-multiple-inheritance) illustrates another example of how to validate types that use multiple inheritance and union types.
+
 If a sub-type inherits properties having the same name from at least two of its parent types, the sub-type keeps all restrictions applied to those properties with two exceptions: 1) a "pattern" facet when a parent type already declares a "pattern" facet 2) a user-defined facet when another user-defined facet has the same value. In these cases, an invalid type declaration occurs.
 
 ### Inline Type Declarations

From 7c9ea8b34614e7b5a546e89ada3bc0e45de68b9f Mon Sep 17 00:00:00 2001
From: Christian Vogel 
Date: Fri, 29 Apr 2016 17:34:19 +0100
Subject: [PATCH 212/241] clarified grant types for OAuth 2.0 based on previous
 discussion in issue #99

---
 versions/raml-10/raml-10.md | 10 +++++-----
 1 file changed, 5 insertions(+), 5 deletions(-)

diff --git a/versions/raml-10/raml-10.md b/versions/raml-10/raml-10.md
index ac22b4ba..8eefd38b 100644
--- a/versions/raml-10/raml-10.md
+++ b/versions/raml-10/raml-10.md
@@ -1134,7 +1134,7 @@ CatOrDog: # follows restrictions applied to the type 'Cat'
   color: "brown"
 ```
 
-
+
 Imagine a more complex example of a union type used in a multiple inheritance type expression:
 
 ```yaml
@@ -1205,7 +1205,7 @@ types:
   Board:
     properties:
       members: Person[] # invalid use of type expression '[]' and as a property type
- ```
+```
 
 A RAML Processor MUST be able to interpret and apply JSON Schema and XML Schema.
 
@@ -2439,7 +2439,7 @@ Security schemes of this type have the following properties:
 |:--------|:------------|
 |authorizationUri| The URI of the *Authorization Endpoint* as defined in [RFC6749 Section 3.1](https://tools.ietf.org/html/rfc6749#section-3.1)
 |accessTokenUri| The URI of the *Token Endpoint* as defined in [RFC6749 Section 3.2](https://tools.ietf.org/html/rfc6749#section-3.2)
-|authorizationGrants| A list of the authorization grants supported by the API as defined in RFC6749 Sections [4.1](https://tools.ietf.org/html/rfc6749#section-4.1), [4.2](https://tools.ietf.org/html/rfc6749#section-4.2), [4.3](https://tools.ietf.org/html/rfc6749#section-4.3) and [4.4](https://tools.ietf.org/html/rfc6749#section-4.4), which can be any of the following grants: code, token, owner, or credentials.
+|authorizationGrants| A list of the authorization grants supported by the API as defined in RFC6749 Sections [4.1](https://tools.ietf.org/html/rfc6749#section-4.1), [4.2](https://tools.ietf.org/html/rfc6749#section-4.2), [4.3](https://tools.ietf.org/html/rfc6749#section-4.3) and [4.4](https://tools.ietf.org/html/rfc6749#section-4.4), which can be any of the following grants: `authorization_code`, `password`, `client_credentials`, `implicit`, or `refresh_token`.
 |scopes| A list of scopes supported by the API as defined in [RFC6749 Section 3.3](https://tools.ietf.org/html/rfc6749#section-3.3)
 
 OAuth 2.0 authentication follows the standard described in [RFC6749](https://tools.ietf.org/html/rfc6749). The following example shows how to set OAuth 2.0 properties:
@@ -2951,7 +2951,7 @@ When RAML or YAML files are included, RAML parsers MUST not only read the conten
 * application/yaml
 * application/x-yaml
 
-Otherwise, if RAML parsers fail to parse the content and append structures, the contents of the file are included as a scalar. 
+Otherwise, if RAML parsers fail to parse the content and append structures, the contents of the file are included as a scalar.
 
 Because the parsing context of the included files is not shared between the included file and its parent, an included file SHALL NOT use a YAML reference to an anchor in a separate file. Likewise, a reference made from a parent file SHALL NOT reference a structure anchor defined in an included file. These rules simplify RAML definitions.
 
@@ -3137,7 +3137,7 @@ To apply any combination of overlays and/or extensions, all must share the same
 
 1. Apply the first overlay or extension to the master RAML document, producing a modified API definition and validating the result in the case of an overlay.
 2. Apply the second overlay or extension to the modified API definition as if the latter were the master RAML document, and again validate the result in the case of an overlay.
-3. Repeat the previous step until the last overlay or extension is applied. 
+3. Repeat the previous step until the last overlay or extension is applied.
 4. Resolve all !include tags before any application of the merging algorithm, validate restrictions on overlays after each overlay is applied, and apply all inheritances of types, resource types, traits, and annotation types.
 
 #### Overlays

From 5042abe17bde58090828834a8624f7e18f5edb0e Mon Sep 17 00:00:00 2001
From: Christian Vogel 
Date: Fri, 29 Apr 2016 18:25:18 +0100
Subject: [PATCH 213/241] add 'signatures' to OAuth 1.0

---
 versions/raml-10/raml-10.md | 20 ++++++++++----------
 1 file changed, 10 insertions(+), 10 deletions(-)

diff --git a/versions/raml-10/raml-10.md b/versions/raml-10/raml-10.md
index 8eefd38b..10fee065 100644
--- a/versions/raml-10/raml-10.md
+++ b/versions/raml-10/raml-10.md
@@ -2409,26 +2409,26 @@ Security schemes of this type have the following properties:
 
 |Property |Description |
 |:--------|:------------|
-|requestTokenUri| The URI of the *Temporary Credential Request endpoint* as defined in [RFC5849 Section 2.1](https://tools.ietf.org/html/rfc5849#section-2.1)
-|authorizationUri| The URI of the *Resource Owner Authorization endpoint* as defined in [RFC5849 Section 2.2](https://tools.ietf.org/html/rfc5849#section-2.2)
-|tokenCredentialsUri| The URI of the *Token Request endpoint* as defined in [RFC5849 Section 2.3](https://tools.ietf.org/html/rfc5849#section-2.3)
+| requestTokenUri | The URI of the *Temporary Credential Request endpoint* as defined in [RFC5849 Section 2.1](https://tools.ietf.org/html/rfc5849#section-2.1)
+| authorizationUri | The URI of the *Resource Owner Authorization endpoint* as defined in [RFC5849 Section 2.2](https://tools.ietf.org/html/rfc5849#section-2.2)
+| tokenCredentialsUri | The URI of the *Token Request endpoint* as defined in [RFC5849 Section 2.3](https://tools.ietf.org/html/rfc5849#section-2.3)
+| signature | A list of signature methods used by the Authorization server, which can be any of the following: `HMAC-SHA1`, `RSA-SHA1`, or `PLAINTEXT`. If this property is missing, it is assumed that the Authentication server allows any signature method defined in [RFC5849 Section 3.4](https://tools.ietf.org/html/rfc5849#section-3.4).
 
 OAuth 1.0 authentication follows the standard described in [RFC5849](https://tools.ietf.org/html/rfc5849). The following example shows how to set OAuth 1.0 properties:
 
 ```yaml
 #%RAML 1.0
-title: Dropbox API
-version: 1
-baseUri: https://api.dropbox.com/{version}
+title: My Sample API
 securitySchemes:
   oauth_1_0:
-    description: |
+    description:|
       OAuth 1.0 continues to be supported for all API requests, but OAuth 2.0 is now preferred.
     type: OAuth 1.0
     settings:
-      requestTokenUri: https://api.dropbox.com/1/oauth/request_token
-      authorizationUri: https://www.dropbox.com/1/oauth/authorize
-      tokenCredentialsUri: https://api.dropbox.com/1/oauth/access_token
+      requestTokenUri: https://api.mysampleapi.com/1/oauth/request_token
+      authorizationUri: https://api.mysampleapi.com/1/oauth/authorize
+      tokenCredentialsUri: https://api.mysampleapi.com/1/oauth/access_token
+      signatures: [ 'HMAC-SHA1', 'PLAINTEXT' ]
 ```
 
 ##### OAuth 2.0

From 288bb122bbf528824b2e14d2eceb63d7a23bcfe7 Mon Sep 17 00:00:00 2001
From: Christian Vogel 
Date: Fri, 29 Apr 2016 18:27:12 +0100
Subject: [PATCH 214/241] append trailing 's' to signature node

---
 versions/raml-10/raml-10.md | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/versions/raml-10/raml-10.md b/versions/raml-10/raml-10.md
index 10fee065..574eab0e 100644
--- a/versions/raml-10/raml-10.md
+++ b/versions/raml-10/raml-10.md
@@ -2412,7 +2412,7 @@ Security schemes of this type have the following properties:
 | requestTokenUri | The URI of the *Temporary Credential Request endpoint* as defined in [RFC5849 Section 2.1](https://tools.ietf.org/html/rfc5849#section-2.1)
 | authorizationUri | The URI of the *Resource Owner Authorization endpoint* as defined in [RFC5849 Section 2.2](https://tools.ietf.org/html/rfc5849#section-2.2)
 | tokenCredentialsUri | The URI of the *Token Request endpoint* as defined in [RFC5849 Section 2.3](https://tools.ietf.org/html/rfc5849#section-2.3)
-| signature | A list of signature methods used by the Authorization server, which can be any of the following: `HMAC-SHA1`, `RSA-SHA1`, or `PLAINTEXT`. If this property is missing, it is assumed that the Authentication server allows any signature method defined in [RFC5849 Section 3.4](https://tools.ietf.org/html/rfc5849#section-3.4).
+| signatures | A list of signature methods used by the Authorization server, which can be any of the following: `HMAC-SHA1`, `RSA-SHA1`, or `PLAINTEXT`. If this property is missing, it is assumed that the Authentication server allows any signature method defined in [RFC5849 Section 3.4](https://tools.ietf.org/html/rfc5849#section-3.4).
 
 OAuth 1.0 authentication follows the standard described in [RFC5849](https://tools.ietf.org/html/rfc5849). The following example shows how to set OAuth 1.0 properties:
 

From 32bb02dc11871cf54b08e1362db0f759b45fc85b Mon Sep 17 00:00:00 2001
From: Christian Vogel 
Date: Fri, 29 Apr 2016 19:26:06 +0100
Subject: [PATCH 215/241] some wordsmithing

---
 versions/raml-10/raml-10.md | 10 ++++------
 1 file changed, 4 insertions(+), 6 deletions(-)

diff --git a/versions/raml-10/raml-10.md b/versions/raml-10/raml-10.md
index 1d72a850..362e1d17 100644
--- a/versions/raml-10/raml-10.md
+++ b/versions/raml-10/raml-10.md
@@ -916,11 +916,9 @@ The ​**file**​ type can constrain the content to send through forms. When th
 | minLength? | Specifies the minimum number of bytes for a parameter value. The value MUST be equal to or greater than 0.

      **Default:** `0`
 | maxLength? | Specifies the maximum number of bytes for a parameter value. The value MUST be equal to or greater than 0.

      **Default:** `2147483647`
 
-### Null Type
+#### Null Type
 ​
-RAML handles null data values in payloads, annotations, and other constructs. Nullable properties must be represented as a single `null` type, a union of the non-null and `null` types, or by suffixing the type with a trailing question mark `?` which is the equivalent to a union between `null` and a type, for example: `null | number`.
-
-For headers, URI parameters, and query parameters, only the string value "null" (case-sensitive) validates against the null type, and in turn the string value "null" (case-sensitive) deserializes to the null type.
+In RAML, the type `null` is a special scalar type that only matches null data values, which in JSON is JSON's `null` and in XML `xsi:nil`. RAML handles null data values in payloads, annotations, and other constructs. A RAML processor MUST apply standard serialization and deserialization rules as for any other type except for headers, URI parameters, and query parameters, where only the string value "null" (case-sensitive) validates against the null type, and in turn the string value "null" (case-sensitive) deserializes to the null type.
 
 In the following example, the type of an object and has two required properties, `name` and `comment`, both defaulting to type `string`. In `example`, `name` is assigned a string value, but comment is null and this is _not_ allowed because RAML expects a string.
 
@@ -960,7 +958,7 @@ example:
   comment: # Providing a value or not providing a value here is allowed.
 ```
 
-Declaring the type of a property to be `null` causes a RAML processor to forbid an instance to have a value. In a RAML context that requires *values* of type `null` (vs just type declarations), the usual YAML `null` is used, e.g. when the type is `number | null` you may use `enum: [ 1, 2, ~ ]` or more explicitly/verbosely `enum: [ 1, 2, !!null "" ]`; in non-inline notation you can just omit the value completely, of course.
+Declaring the type of a property to be `null` means that it does not have any valid instance. In a RAML context that requires *values* of type `null` (vs just type declarations), the usual YAML `null` is used, e.g. when the type is `null | number` you may use `enum: [ 1, 2, ~ ]` or more explicitly/verbosely `enum: [ 1, 2, !!null "" ]`; in non-inline notation you can just omit the value completely, of course.
 
 ### User-defined Facets
 
@@ -2643,7 +2641,7 @@ title: Illustrating annotations
 mediaType: application/json
 annotationTypes:
   deprecated: null
-  experimental: string | null
+  experimental: null | string
   feedbackRequested: string?
   testHarness:
     type: string # This line may be omitted as it's the default type

From 4294aa8401813c21708e1f6d0c13af6abc23843b Mon Sep 17 00:00:00 2001
From: Christian Vogel 
Date: Fri, 29 Apr 2016 19:29:48 +0100
Subject: [PATCH 216/241] clarification around when authorizationUri in OAuth
 2.0 is mandatory and when it is not

---
 versions/raml-10/raml-10.md | 4 ++--
 1 file changed, 2 insertions(+), 2 deletions(-)

diff --git a/versions/raml-10/raml-10.md b/versions/raml-10/raml-10.md
index 8eefd38b..5bc69ea2 100644
--- a/versions/raml-10/raml-10.md
+++ b/versions/raml-10/raml-10.md
@@ -2437,8 +2437,8 @@ Security schemes of this type have the following properties:
 
 |Property |Description |
 |:--------|:------------|
-|authorizationUri| The URI of the *Authorization Endpoint* as defined in [RFC6749 Section 3.1](https://tools.ietf.org/html/rfc6749#section-3.1)
-|accessTokenUri| The URI of the *Token Endpoint* as defined in [RFC6749 Section 3.2](https://tools.ietf.org/html/rfc6749#section-3.2)
+|authorizationUri| The URI of the *Authorization Endpoint* as defined in [RFC6749 Section 3.1](https://tools.ietf.org/html/rfc6749#section-3.1). Providing an Authorization Endpoint is only mandatory using either the `authorization_code` or `implicit` grant type. It is not mandatory for any other.
+|accessTokenUri| The URI of the *Token Endpoint* as defined in [RFC6749 Section 3.2](https://tools.ietf.org/html/rfc6749#section-3.2).
 |authorizationGrants| A list of the authorization grants supported by the API as defined in RFC6749 Sections [4.1](https://tools.ietf.org/html/rfc6749#section-4.1), [4.2](https://tools.ietf.org/html/rfc6749#section-4.2), [4.3](https://tools.ietf.org/html/rfc6749#section-4.3) and [4.4](https://tools.ietf.org/html/rfc6749#section-4.4), which can be any of the following grants: `authorization_code`, `password`, `client_credentials`, `implicit`, or `refresh_token`.
 |scopes| A list of scopes supported by the API as defined in [RFC6749 Section 3.3](https://tools.ietf.org/html/rfc6749#section-3.3)
 

From 226b0a059cb9a3fa28e3d8f0a7ea96d365865dc0 Mon Sep 17 00:00:00 2001
From: Christian Vogel 
Date: Fri, 29 Apr 2016 19:43:20 +0100
Subject: [PATCH 217/241] wordsmithing and added an additional example for file
 type

---
 versions/raml-10/raml-10.md | 14 +++++++++++++-
 1 file changed, 13 insertions(+), 1 deletion(-)

diff --git a/versions/raml-10/raml-10.md b/versions/raml-10/raml-10.md
index 2ee3b1b2..e0537f0a 100644
--- a/versions/raml-10/raml-10.md
+++ b/versions/raml-10/raml-10.md
@@ -912,10 +912,22 @@ The ​**file**​ type can constrain the content to send through forms. When th
 
 | Facet | Description |
 |:--------|:------------|
-| fileTypes? | A list of valid content-types in `*/*` notation for the file.
+| fileTypes? | A list of valid content-type strings for the file. The file type `*/*` MUST be a valid value.
 | minLength? | Specifies the minimum number of bytes for a parameter value. The value MUST be equal to or greater than 0.

      **Default:** `0`
 | maxLength? | Specifies the maximum number of bytes for a parameter value. The value MUST be equal to or greater than 0.

      **Default:** `2147483647`
 
+```yaml
+types:
+  userPicture:
+    type: file
+    fileTypes: ['image/jpeg', 'image/png']
+    maxLength: 307200
+  customFile:
+    type: file
+    fileTypes: ['*/*'] # any file type allowed
+    maxLength: 1048576
+```
+
 ### User-defined Facets
 
 Facets express various additional restrictions beyond those which types impose on their instances, such as the optional `minimum` and `maximum` facets for numbers, or the `enum` facet for scalars. In addition to the built-in facets, RAML provides a way to declare user-defined facets for any data type.

From 7cb07a021ad110f958b7864bef362d098da86b0c Mon Sep 17 00:00:00 2001
From: Christian Vogel 
Date: Fri, 29 Apr 2016 20:03:10 +0100
Subject: [PATCH 218/241] clarified that description may be GFM

---
 versions/raml-10/raml-10.md | 10 +++++-----
 1 file changed, 5 insertions(+), 5 deletions(-)

diff --git a/versions/raml-10/raml-10.md b/versions/raml-10/raml-10.md
index e0537f0a..2d9e7069 100644
--- a/versions/raml-10/raml-10.md
+++ b/versions/raml-10/raml-10.md
@@ -426,7 +426,7 @@ A type declaration can extend a built-in type or other custom type, or add more
 | example? | An example of an instance of this type that can be used, for example, by documentation generators to generate sample values for an object of this type. The "example" property MUST not be available when the "examples" property is already defined. See section [Examples](#defining-examples-in-raml) for more information.
 | examples? |  An object containing named examples of instances of this type. This can be used, for example, by documentation generators to generate sample values for an object of this type. The "examples" property MUST not be available when the "example" property is already defined. See section [Examples](#defining-examples-in-raml) for more information.
 | displayName? | An alternate, human-friendly name for the type
-| description? | A substantial, human-friendly description of the type
+| description? | A substantial, human-friendly description of the type. Its value is a string and MAY be formatted using [markdown](#markdown).
 | (<annotationName>)? | [Annotations](#annotations) to be applied to this type. An annotation is a property having a key that begins with "(" and ends with ")". The text enclosed in parentheses is the annotation name.
 | facets? | A map of additional, user-defined restrictions that will be inherited and applied by any extending subtype. See section [User-defined Facets](#user-defined-facets) for more information.
 | xml? | The capability to configure [XML serialization of this type instance](#xml-serialization-of-type-instances).
@@ -1354,7 +1354,7 @@ The map can contain the following additional facets:
 | Facet | Description |
 |:--------|:------------|
 | displayName? | An alternate, human-friendly name for the example. If the example is part of an examples node, the default value is the unique identifier that is defined for this example.
-| description? | A longer, human-friendly description of the example.
+| description? | A substantial, human-friendly description for an example. Its value is a string and MAY be formatted using [markdown](#markdown).
 | (<annotationName>)? | [Annotations](#annotations) to be applied to this example. An annotation is a property having a key that begins with "(" and ends with ")". The text enclosed in parentheses is the annotation name.
 | value | The actual example of a type instance.
 | strict? | Validates the example against any type declaration (the default), or not. Set this to false avoid validation.
@@ -1578,7 +1578,7 @@ The value of a resource property is an object whose properties are described in
 |Property | Description |
 |:--------|:------------|
 | displayName? | An alternate, human-friendly name for the resource. If the displayName property is not defined for a resource, documentation tools SHOULD refer to the resource by its property key, which acts as the resource name. For example, tools should refer to the relative URI /jobs.
-| description? | A longer, human-friendly description of the resource.
+| description? | A substantial, human-friendly description of a resource. Its value is a string and MAY be formatted using [markdown](#markdown).
 | (<annotationName>)? | [Annotations](#annotations) to be applied to this resource. An annotation is a property having a key that begins with "(" and ends with ")". The text enclosed in parentheses is the annotation name.
 | get?
      patch?
      put?
      post?
      delete?
      options?
      head? | The object describing the [method](#methods).
 | is? | A list of [traits to apply](#applying-resource-types-and-traits) to all methods declared (implicitly or explicitly) for this resource. Individual methods can override this declaration.
@@ -1904,7 +1904,7 @@ The value of a response declaration is an object that can contain any of the fol
 
 |Property | Description |
 |:--------|:------------|
-| description? | A human-friendly description of the response
+| description? | A substantial, human-friendly description of a response. Its value is a string and MAY be formatted using [markdown](#markdown).
 | (<annotationName>) | [Annotations](#annotations) to be applied to this response. An annotation is a property having a key that begins with "(" and ends with ")". The text enclosed in parentheses is the annotation name.
 | headers? | Detailed information about any response headers returned by this method
 | body? | The body of the response
@@ -2342,7 +2342,7 @@ The security scheme is declared using the following properties:
 |:----------|:----------|
 | type | The security schemes property that MUST be used to specify the API security mechanisms, including the required settings and the authentication methods that the API supports. One API-supported authentication method is allowed. The value MUST be one of the following methods: OAuth 1.0, OAuth 2.0, Basic Authentication, Digest Authentication, Pass Through, x-<other>
 | displayName? | An alternate, human-friendly name for the security scheme.
-| description? | Information that MAY be used to describe a security scheme.
+| description? | Information that MAY be used to describe a security scheme. Its value is a string and MAY be formatted using [markdown](#markdown).
 | [describedBy?](#describedby) | A description of the following security-related request components determined by the scheme: the headers, query parameters, or responses. As a best practice, even for standard security schemes, API designers SHOULD describe these properties of security schemes. Including the security scheme description completes the API documentation.
 | settings? | The [settings](#settings) attribute MAY be used to provide security scheme-specific information.
 

From f3dd875e7cbb478b21ecd02fb07a1ceab7badb1a Mon Sep 17 00:00:00 2001
From: Christian Vogel 
Date: Sun, 1 May 2016 10:39:34 +0100
Subject: [PATCH 219/241] removed refresh_token and added absolute URIs to the
 list of grant types

---
 versions/raml-10/raml-10.md | 4 ++--
 1 file changed, 2 insertions(+), 2 deletions(-)

diff --git a/versions/raml-10/raml-10.md b/versions/raml-10/raml-10.md
index 2d9e7069..0fcc1264 100644
--- a/versions/raml-10/raml-10.md
+++ b/versions/raml-10/raml-10.md
@@ -2451,7 +2451,7 @@ Security schemes of this type have the following properties:
 |:--------|:------------|
 |authorizationUri| The URI of the *Authorization Endpoint* as defined in [RFC6749 Section 3.1](https://tools.ietf.org/html/rfc6749#section-3.1). Providing an Authorization Endpoint is only mandatory using either the `authorization_code` or `implicit` grant type. It is not mandatory for any other.
 |accessTokenUri| The URI of the *Token Endpoint* as defined in [RFC6749 Section 3.2](https://tools.ietf.org/html/rfc6749#section-3.2).
-|authorizationGrants| A list of the authorization grants supported by the API as defined in RFC6749 Sections [4.1](https://tools.ietf.org/html/rfc6749#section-4.1), [4.2](https://tools.ietf.org/html/rfc6749#section-4.2), [4.3](https://tools.ietf.org/html/rfc6749#section-4.3) and [4.4](https://tools.ietf.org/html/rfc6749#section-4.4), which can be any of the following grants: `authorization_code`, `password`, `client_credentials`, `implicit`, or `refresh_token`.
+|authorizationGrants| A list of the authorization grants supported by the API as defined in RFC6749 Sections [4.1](https://tools.ietf.org/html/rfc6749#section-4.1), [4.2](https://tools.ietf.org/html/rfc6749#section-4.2), [4.3](https://tools.ietf.org/html/rfc6749#section-4.3) and [4.4](https://tools.ietf.org/html/rfc6749#section-4.4), which can be either any of the following grants: `authorization_code`, `password`, `client_credentials`, or `implicit`; or any absolute URI as defined in section [4.5](defined in https://tools.ietf.org/html/rfc6749#section-4.5).
 |scopes| A list of scopes supported by the API as defined in [RFC6749 Section 3.3](https://tools.ietf.org/html/rfc6749#section-3.3)
 
 OAuth 2.0 authentication follows the standard described in [RFC6749](https://tools.ietf.org/html/rfc6749). The following example shows how to set OAuth 2.0 properties:
@@ -2492,7 +2492,7 @@ securitySchemes:
     settings:
       authorizationUri: https://www.dropbox.com/1/oauth2/authorize
       accessTokenUri: https://api.dropbox.com/1/oauth2/token
-      authorizationGrants: [ authorization_code, refresh_token ]
+      authorizationGrants: [ authorization_code, refresh_token, 'urn:ietf:params:oauth:grant-type:saml2-bearer' ]
 ```
 
 ##### Basic Authentication

From b9e50d98a5c029bfdc55ba5cea77c3a455198a6c Mon Sep 17 00:00:00 2001
From: Christian Vogel 
Date: Tue, 3 May 2016 06:30:37 +0100
Subject: [PATCH 220/241] added an example to array type

---
 versions/raml-10/raml-10.md | 13 ++++++++++---
 1 file changed, 10 insertions(+), 3 deletions(-)

diff --git a/versions/raml-10/raml-10.md b/versions/raml-10/raml-10.md
index 0fcc1264..9f5675d9 100644
--- a/versions/raml-10/raml-10.md
+++ b/versions/raml-10/raml-10.md
@@ -758,12 +758,19 @@ types:
   Email:
     type: object
     properties:
-      name:
-        type: string
+      subject: string
+      body: string
   Emails:
     type: Email[]
     minItems: 1
     uniqueItems: true
+    example: # example that contains array
+      - # start item 1
+        subject: My Email 1
+        body: This is the text for email 1.
+      - # start item 2
+        subject: My Email 2
+        body: This is the text for email 2.  
 ```
 
 ```yaml
@@ -777,7 +784,7 @@ types:
     type: array
     items: Email
     minItems: 1
-    uniqueItems: true
+    uniqueItems: true 
 ```
 
 Using `Email[]` is equivalent to using `type: array`.  The `items` facet defines the `Email` type as the one each array item inherits from.

From 627e5d807d4be432aa33ac18948632173ce8af04 Mon Sep 17 00:00:00 2001
From: Christian Vogel 
Date: Wed, 4 May 2016 07:50:52 +0100
Subject: [PATCH 221/241] last wordsmithing before closing out

---
 versions/raml-10/raml-10.md | 4 ++--
 1 file changed, 2 insertions(+), 2 deletions(-)

diff --git a/versions/raml-10/raml-10.md b/versions/raml-10/raml-10.md
index 362e1d17..b35862fb 100644
--- a/versions/raml-10/raml-10.md
+++ b/versions/raml-10/raml-10.md
@@ -918,7 +918,7 @@ The ​**file**​ type can constrain the content to send through forms. When th
 
 #### Null Type
 ​
-In RAML, the type `null` is a special scalar type that only matches null data values, which in JSON is JSON's `null` and in XML `xsi:nil`. RAML handles null data values in payloads, annotations, and other constructs. A RAML processor MUST apply standard serialization and deserialization rules as for any other type except for headers, URI parameters, and query parameters, where only the string value "null" (case-sensitive) validates against the null type, and in turn the string value "null" (case-sensitive) deserializes to the null type.
+In RAML, the type `null` is a scalar type that allows only null data values. Specifically, in YAML it allows only YAML's `null` (or its equivalent representations, such as `~`), in JSON it allows only JSON's `null`, and in XML it allows only XML's `xsi:nil`. In headers, URI parameters, and query parameters, the `null` type only allows the string value "null" (case-sensitive); and in turn an instance having the string value "null" (case-sensitive), when described with the `null` type, deserializes to a null value.
 
 In the following example, the type of an object and has two required properties, `name` and `comment`, both defaulting to type `string`. In `example`, `name` is assigned a string value, but comment is null and this is _not_ allowed because RAML expects a string.
 
@@ -958,7 +958,7 @@ example:
   comment: # Providing a value or not providing a value here is allowed.
 ```
 
-Declaring the type of a property to be `null` means that it does not have any valid instance. In a RAML context that requires *values* of type `null` (vs just type declarations), the usual YAML `null` is used, e.g. when the type is `null | number` you may use `enum: [ 1, 2, ~ ]` or more explicitly/verbosely `enum: [ 1, 2, !!null "" ]`; in non-inline notation you can just omit the value completely, of course.
+Declaring the type of a property to be `null` represents the lack of a value in a type instance. In a RAML context that requires *values* of type `null` (vs just type declarations), the usual YAML `null` is used, e.g. when the type is `null | number` you may use `enum: [ 1, 2, ~ ]` or more explicitly/verbosely `enum: [ 1, 2, !!null "" ]`; in non-inline notation you can just omit the value completely, of course.
 
 ### User-defined Facets
 

From 52596c77fa8b18355a82aeb29b02a7ca499c0fb5 Mon Sep 17 00:00:00 2001
From: Christian Vogel 
Date: Wed, 4 May 2016 08:01:39 +0100
Subject: [PATCH 222/241] added some behaviour clarifications to the default
 facet

---
 versions/raml-10/raml-10.md | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/versions/raml-10/raml-10.md b/versions/raml-10/raml-10.md
index 21d1295c..c5470642 100644
--- a/versions/raml-10/raml-10.md
+++ b/versions/raml-10/raml-10.md
@@ -420,7 +420,7 @@ A type declaration can extend a built-in type or other custom type, or add more
 
 | Facet  | Description |
 |:----------|:----------|
-| default? | A default value for a type.
+| default? | A default value for a type. When an API request is completely missing the instance of a type, for example when a query parameter described by a type is entirely missing from the request, then the API must act as if the API client had sent an instance of that type with the instance value being the value in the default facet. Similarly, when the API response is completely missing the instance of a type, the client must act as if the API server had returned an instance of that type with the instance value being the value in the default facet. A special case is made for URI parameters: for these, the client MUST substitute the value in the default facet if no instance of the URI parameter was given.
 | schema? | An alias for the equivalent "type" property for compatibility with RAML 0.8. Deprecated - API definitions should use the "type" property because the "schema" alias for that property name might be removed in a future RAML version. The "type" property supports XML and JSON schemas.
 | type? | A base type which the current type extends or just wraps. The value of a type node MUST be either a) the name of a user-defined type or b) the name of a built-in RAML data type (object, array, or one of the scalar types) or c) an inline type declaration.
 | example? | An example of an instance of this type that can be used, for example, by documentation generators to generate sample values for an object of this type. The "example" property MUST not be available when the "examples" property is already defined. See section [Examples](#defining-examples-in-raml) for more information.

From 8145b2256101c7e0e05b15dd1cbbe5b72147ec0e Mon Sep 17 00:00:00 2001
From: Christian Vogel 
Date: Wed, 4 May 2016 10:31:58 +0100
Subject: [PATCH 223/241] fixed default descriptio of xml property 'name' to
 reflect properties as well

---
 versions/raml-10/raml-10.md | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/versions/raml-10/raml-10.md b/versions/raml-10/raml-10.md
index c5470642..b6f6edd2 100644
--- a/versions/raml-10/raml-10.md
+++ b/versions/raml-10/raml-10.md
@@ -1482,7 +1482,7 @@ To facilitate the potentially complex process of serialization to XML, RAML intr
 |:---------|:------:|:-----------------|
 | attribute? | `boolean` | `true` serializes a type instance as an XML attribute. Can be `true` only for scalar types.

      **Default:** `false`
 | wrapped? | `boolean` | `true` wraps a type instance in its own XML element. Cannot be `true` for scalar types or `true` at the same moment `attribute` is `true`. 

      **Default:** `false`
-| name? | `string` | Overrides the name of the XML element or XML attribute.

      **Default:** the name of the type
+| name? | `string` | Overrides the name of the XML element or XML attribute.

      **Default:** name of either a type or property
 | namespace? | `string` | Configures the name of the XML namespace.
 | prefix? | `string` |  Configures the prefix used during serialization to XML.
 

From bb994f28022b34f1385e01682ec514a015387b7b Mon Sep 17 00:00:00 2001
From: Christian Vogel 
Date: Wed, 4 May 2016 18:03:48 +0100
Subject: [PATCH 224/241] added common language such as nodes, key-value pairs,
 facets, etc.

---
 versions/raml-10/raml-10.md | 286 ++++++++++++++++++------------------
 1 file changed, 146 insertions(+), 140 deletions(-)

diff --git a/versions/raml-10/raml-10.md b/versions/raml-10/raml-10.md
index b6f6edd2..295e647f 100644
--- a/versions/raml-10/raml-10.md
+++ b/versions/raml-10/raml-10.md
@@ -107,7 +107,7 @@ To facilitate the automated processing of RAML documents, RAML imposes the follo
 
 The root section of the RAML document describes the basic information about an API, such as its title and version. The root section also defines assets used elsewhere in the RAML document, such as types and traits.
 
-RAML-documented API definition properties MAY appear in any order. Processors MUST preserve the order of properties of the same kind within the same node of the definition tree. Examples of such properties are resources that appear at the same level of the resource tree, methods for a given resource, parameters for a given method, and properties at the same level in a given type. Processors MUST also preserve the order of items within arrays.
+Nodes in a RAML-documented API definition MAY appear in any order. Processors MUST preserve the order of nodes of the same kind within the same node of the definition tree. Examples of such nodes are resources that appear at the same level of the resource tree, methods for a given resource, parameters for a given method, and nodes at the same level in a given type. Processors MUST also preserve the order of items within arrays.
 
 This example shows a small part of a RAML API definition for the GitHub v3 public API.
 
@@ -132,9 +132,9 @@ securedBy: [ oauth_2_0 ]
     get:
 ```
 
-The following table enumerates the possible properties at the root of a RAML document:
+The following table enumerates the possible nodes at the root of a RAML document:
 
-| Property  | Description |
+| Name  | Description |
 |:----------|:----------|
 | title | A short, plain-text label for the API. Its value is a string.
 | description? | A substantial, human-friendly description of the API. Its value is a string and MAY be formatted using [markdown](#markdown).
@@ -144,26 +144,26 @@ The following table enumerates the possible properties at the root of a RAML doc
 | protocols? | The [protocols](#protocols) supported by the API.
 | mediaType? | The [default media types](#default-media-type) to use for request and response bodies (payloads), for example "application/json".
 | documentation? | Additional overall [documentation](#user-documentation) for the API.
-| schemas? | An alias for the equivalent "types" property for compatibility with RAML 0.8. Deprecated - API definitions should use the "types" property because a future RAML version might remove the "schemas" alias for that property name. The "types" property supports XML and JSON schemas.
-| types? | Declarations of [(data) types](#raml-data-types) for use within the API.
+| schemas? | An alias for the equivalent "types" node for compatibility with RAML 0.8. Deprecated - API definitions should use the "types" node because a future RAML version might remove the "schemas" alias with that node. The "types" node supports XML and JSON schemas.
+| types? | Declarations of [(data) types](#defining-types) for use within the API.
 | traits? | Declarations of [traits](#resource-types-and-traits) for use within the API.
 | resourceTypes? | Declarations of [resource types](#resource-types-and-traits) for use within the API.
 | annotationTypes? | Declarations of [annotation types](#declaring-annotation-types) for use by annotations.
-| (<annotationName>)? | [Annotations](#annotations) to be applied to this API. An annotation is a property having a key that begins with "(" and ends with ")". The text enclosed in parentheses is the annotation name.
+| (<annotationName>)? | [Annotations](#annotations) to be applied to this API. An annotation is a map having a key that begins with "(" and ends with ")" where the text enclosed in parentheses is the annotation name, and the value is an instance of that annotation.
 | securitySchemes? | Declarations of [security schemes](#security-schemes) for use within the API.
 | securedBy? | The [security schemes](#applying-security-schemes) that apply to every resource and method in the API.
 | uses? | Imported external [libraries](#libraries) for use within the API.
-| /<relativeUri>? | The resources of the API, identified as relative URIs that begin with a slash (/). A [resource property](#resources-and-nested-resources) is one that begins with the slash and is either at the root of the API definition or a child of a resource property. For example, /users and /{groupId}.
+| /<relativeUri>? | The resources of the API, identified as relative URIs that begin with a slash (/). A [resource node](#resources-and-nested-resources) is one that begins with the slash and is either at the root of the API definition or a child of a resource node. For example, /users and /{groupId}.
 
 The "schemas" and "types" nodes are mutually exclusive and synonymous: processors MUST NOT allow both to be specified at the root-level of an API definition. We recommended using the "types" node instead of "schemas" because the schemas alias is deprecated and might be removed in a future RAML version.
 
 ### User Documentation
 
-The OPTIONAL **documentation** property includes a variety of documents that serve as user guides and reference documentation for the API. Such documents can clarify how the API works or provide technical and business context.
+The OPTIONAL **documentation** node includes a variety of documents that serve as user guides and reference documentation for the API. Such documents can clarify how the API works or provide technical and business context.
 
-The value of the documentation property is a sequence of one or more documents. Each document is an object that MUST have exactly two properties described in following table:
+The value of the documentation node is a sequence of one or more documents. Each document is a map that MUST have exactly two key-value pairs described in following table:
 
-| Property  | Description |
+| Name  | Description |
 |:----------|:----------|
 | title | Title of the document. Its value MUST be a non-empty string.
 | content | Content of the document. Its value MUST be a non-empty string and MAY be formatted using [markdown](#markdown).
@@ -189,15 +189,15 @@ documentation:
 
 ### Base URI and Base URI Parameters
 
-The OPTIONAL **baseUri** property specifies a URI as an identifier for the API as a whole, and MAY be used the specify the URL at which the API is served (its service endpoint), and which forms the base of the URLs of each of its resources. The baseUri property's value is a string that MUST conform to the URI specification [RFC2396](https://www.ietf.org/rfc/rfc2396.txt) or a [Template URI](#template-uri).
+The OPTIONAL **baseUri** node specifies a URI as an identifier for the API as a whole, and MAY be used the specify the URL at which the API is served (its service endpoint), and which forms the base of the URLs of each of its resources. The value of the baseUri node is a string that MUST conform to the URI specification [RFC2396](https://www.ietf.org/rfc/rfc2396.txt) or a [Template URI](#template-uri).
 
 If the baseUri value is a [Template URI](#template-uri), the following reserved base URI parameter is available.
 
 | URI Parameter | Value |
 |:----------|:----------|
-| version | The value of the root-level version property
+| version | The value of the root-level version node
 
-Any other URI template variables appearing in the baseUri MAY be described explicitly within a **baseUriParameters** property at the root of the API definition. The baseUriParameters property has the same structure and semantics as the [uriParameters](#template-uris-and-uri-parameters) property on a resource property, except that it specifies parameters in the base URI rather than the relative URI of a resource.
+Any other URI template variables appearing in the baseUri MAY be described explicitly within a **baseUriParameters** node at the root of the API definition. The baseUriParameters node has the same structure and semantics as the [uriParameters](#template-uris-and-uri-parameters) node on a resource node, except that it specifies parameters in the base URI rather than the relative URI of a resource.
 
 The following example RAML API definition uses a [Template URI](#template-uri) as the base URI.
 
@@ -239,7 +239,7 @@ baseUri: //api.test.com//common//
 
 ### Protocols
 
-The OPTIONAL **protocols** property specifies the protocols that an API supports. If the protocols property is not explicitly specified, one or more protocols included in the baseUri property is used; if the protocols property is explicitly specified, the property specification overrides any protocol included in the baseUri property. The protocols property MUST be a non-empty array of strings, of values HTTP and/or HTTPS, and is case-insensitive.
+The OPTIONAL **protocols** node specifies the protocols that an API supports. If the protocols node is not explicitly specified, one or more protocols included in the baseUri node is used; if the protocols node is explicitly specified, the node specification overrides any protocol included in the baseUri node. The protocols node MUST be a non-empty array of strings, of values HTTP and/or HTTPS, and is case-insensitive.
 
 The following is an example of an API endpoint that accepts both HTTP and HTTPS requests.
 
@@ -253,9 +253,9 @@ baseUri: https://na1.salesforce.com/services/data/{version}/chatter
 
 ### Default Media Types
 
-Specifying the OPTIONAL **mediaType** property sets the default for return by API requests having a body and for the expected responses. You do not need to specify the media type within every body definition.
+Specifying the OPTIONAL **mediaType** node sets the default for return by API requests having a body and for the expected responses. You do not need to specify the media type within every body definition.
 
-The value of the mediaType property MUST be a sequence of media type strings or a single media type string. The media type applies to requests having a body, the expected responses, and examples using the same sequence of media type strings. Each value needs to conform to the media type specification in [RFC6838](https://tools.ietf.org/html/rfc6838).
+The value of the mediaType node MUST be a sequence of media type strings or a single media type string. The media type applies to requests having a body, the expected responses, and examples using the same sequence of media type strings. Each value needs to conform to the media type specification in [RFC6838](https://tools.ietf.org/html/rfc6838).
 
 This example shows a RAML snippet for an API that accepts and returns a JSON-formatted body. If the remainder of this API specification does not explicitly specify another media type, this API accepts and returns only JSON-formatted bodies.
 
@@ -296,7 +296,7 @@ types:
 
 ### Default Security
 
-Specifying the OPTIONAL **securedBy** property sets the default security schemes for, and protects, every method of every resource in the API. The value of the property is an array of security scheme names. See section [Applying Security Schemes](#applying-security-schemes) for more information, including how to resolve the application of multiple security schemes through inheritance.
+Specifying the OPTIONAL **securedBy** node sets the default security schemes for, and protects, every method of every resource in the API. The value of the node is an array of security scheme names. See section [Applying Security Schemes](#applying-security-schemes) for more information, including how to resolve the application of multiple security schemes through inheritance.
 
 The following example shows an API allowing access through either an OAuth 2.0 security scheme or an OAuth 1.1 security scheme.
 
@@ -394,9 +394,9 @@ RAML Types in a nutshell:
 - You can define types that inherit from other types.
   - Multiple inheritance is allowed.
 - Types are split into four families: external, object, array, and scalar.
-- Types can define two types of members: properties and facets. Both are inherited.
-  - Properties are regular, object oriented properties.
-  - Facets are special _configurations_. You specialize types based on characteristics of facet values.
+- Types can define two types of members: **properties** and **facets**. Both are inherited.
+  - **Properties** are regular, object oriented properties.
+  - **Facets** are special _configurations_. You specialize types based on characteristics of facet values.
     Examples: minLength, maxLength
 - Only object types can declare properties. All types can declare facets.
 - To specialize a scalar type, you implement facets, giving already defined facets a concrete value.
@@ -406,9 +406,9 @@ The following diagram shows the type families and examples of these custom types
 
 ![Types Hierarchy](images/typesHierarchy.png)
 
-### Type Declarations
+### Defining Types
 
-Types can be declared inline where the API expects data, in an OPTIONAL **types** property at the root of the API, or in an included library. To declare a type, you use a map where the key represents the name of the type and its value is a type declaration.
+Types can be declared inline where the API expects data, in an OPTIONAL **types** node at the root of the API, or in an included library. To declare a type, you use a map where the key represents the name of the type and its value is a [type declaration](#type-declarations).
 
 ```yaml
 types:
@@ -416,18 +416,20 @@ types:
     # value is a type declaration
 ```
 
+### Type Declarations
+
 A type declaration can extend a built-in type or other custom type, or add more information to types, such as specific examples or annotations. Here are the facets that all type declarations can have; certain type declarations might have other facets:
 
 | Facet  | Description |
 |:----------|:----------|
 | default? | A default value for a type. When an API request is completely missing the instance of a type, for example when a query parameter described by a type is entirely missing from the request, then the API must act as if the API client had sent an instance of that type with the instance value being the value in the default facet. Similarly, when the API response is completely missing the instance of a type, the client must act as if the API server had returned an instance of that type with the instance value being the value in the default facet. A special case is made for URI parameters: for these, the client MUST substitute the value in the default facet if no instance of the URI parameter was given.
-| schema? | An alias for the equivalent "type" property for compatibility with RAML 0.8. Deprecated - API definitions should use the "type" property because the "schema" alias for that property name might be removed in a future RAML version. The "type" property supports XML and JSON schemas.
+| schema? | An alias for the equivalent "type" facet for compatibility with RAML 0.8. Deprecated - API definitions should use the "type" facet because the "schema" alias for that facet name might be removed in a future RAML version. The "type" facet supports XML and JSON schemas.
 | type? | A base type which the current type extends or just wraps. The value of a type node MUST be either a) the name of a user-defined type or b) the name of a built-in RAML data type (object, array, or one of the scalar types) or c) an inline type declaration.
-| example? | An example of an instance of this type that can be used, for example, by documentation generators to generate sample values for an object of this type. The "example" property MUST not be available when the "examples" property is already defined. See section [Examples](#defining-examples-in-raml) for more information.
-| examples? |  An object containing named examples of instances of this type. This can be used, for example, by documentation generators to generate sample values for an object of this type. The "examples" property MUST not be available when the "example" property is already defined. See section [Examples](#defining-examples-in-raml) for more information.
+| example? | An example of an instance of this type that can be used, for example, by documentation generators to generate sample values for an object of this type. The "example" facet MUST not be available when the "examples" facet is already defined. See section [Examples](#defining-examples-in-raml) for more information.
+| examples? |  Examples of instances of this type. This can be used, for example, by documentation generators to generate sample values for an object of this type. The "examples" facet MUST not be available when the "example" facet is already defined. See section [Examples](#defining-examples-in-raml) for more information.
 | displayName? | An alternate, human-friendly name for the type
 | description? | A substantial, human-friendly description of the type. Its value is a string and MAY be formatted using [markdown](#markdown).
-| (<annotationName>)? | [Annotations](#annotations) to be applied to this type. An annotation is a property having a key that begins with "(" and ends with ")". The text enclosed in parentheses is the annotation name.
+| (<annotationName>)? | [Annotations](#annotations) to be applied to this API. An annotation is a map having a key that begins with "(" and ends with ")" where the text enclosed in parentheses is the annotation name, and the value is an instance of that annotation.
 | facets? | A map of additional, user-defined restrictions that will be inherited and applied by any extending subtype. See section [User-defined Facets](#user-defined-facets) for more information.
 | xml? | The capability to configure [XML serialization of this type instance](#xml-serialization-of-type-instances).
 
@@ -464,7 +466,7 @@ All types that have the built-in object type at the root of their inheritance tr
 | maxProperties? | The maximum number of properties allowed for instances of this type.
 | additionalProperties? | A Boolean that indicates if an object instance has [additional properties](#additional-properties).

      **Default:** `true`
 | discriminator? | Determines the concrete type of an individual object at runtime when, for example, payloads contain ambiguous types due to unions or inheritance. The value must match the name of one of the declared `properties` of a type. Unsupported practices are inline type declarations and [using `discriminator`](#using-discriminator) with non-scalar properties.
-| discriminatorValue? | Identifies the declaring type. Requires including a `discriminator` property in the type declaration. A valid value is an actual value that might identify the type of an individual object and is unique in the hierarchy of the type. Inline type declarations are not supported.

      **Default:** The name of the type
+| discriminatorValue? | Identifies the declaring type. Requires including a `discriminator` facet in the type declaration. A valid value is an actual value that might identify the type of an individual object and is unique in the hierarchy of the type. Inline type declarations are not supported.

      **Default:** The name of the type
 
 An object type is created by explicit inheritance from the built-in type object:
 
@@ -742,7 +744,7 @@ PersonOrDog:
 
 ### Array Types
 
-Array types are declared by using either the array qualifier `[]` at the end of a [type expression](#type-expressions) or `array` as the value of a `type` facet. If you are defining a top-level array type, such as the `Emails` in the examples below, you can declare the following facets in addition to those previously described to further restrict behavior of the array type.
+Array types are declared by using either the array qualifier `[]` at the end of a [type expression](#type-expressions) or `array` as the value of a `type` facet. If you are defining a top-level array type, such as the `Emails` in the examples below, you can declare the following facets in addition to those previously described to further restrict the behavior of the array type.
 
 | Facet  | Description |
 |:----------|:----------|
@@ -890,7 +892,7 @@ The following date type representations MUST be supported:
 | datetime-only | Combined date-only and time-only with a separator of "T", namely yyyy-mm-ddThh:mm:ss\[.ff...\]. Does not support a time zone offset.
 | datetime | A timestamp in one of the following formats:  if the _format_ is omitted or set to `rfc3339`, uses the "date-time" notation of [RFC3339](http://xml2rfc.ietf.org/public/rfc/html/rfc3339.html#anchor14); if _format_ is set to `rfc2616`, uses the format defined in [RFC2616](https://www.ietf.org/rfc/rfc2616.txt).
 
-The additional property _format_ MUST be available only when the type equals _datetime_, and the value MUST be either `rfc3339` or `rfc2616`. Any other values are invalid.
+The additional facet _format_ MUST be available only when the type equals _datetime_, and the value MUST be either `rfc3339` or `rfc2616`. Any other values are invalid.
 
 ```yaml
 types:
@@ -983,7 +985,7 @@ Declaring the type of a property to be `null` represents the lack of a value in
 
 Facets express various additional restrictions beyond those which types impose on their instances, such as the optional `minimum` and `maximum` facets for numbers, or the `enum` facet for scalars. In addition to the built-in facets, RAML provides a way to declare user-defined facets for any data type.
 
-The user-defined facet is declared using the OPTIONAL `facets` property in a type declaration. The value of the `facets` property is a map. The key names the user-defined facet. The corresponding value defines the concrete value that the respective facet can take. The syntax of a [property declaration](#property-declarations) and user-defined facet declaration are the same. A facet restricts instances of a subtype, not its type, based on the concrete value defined in the facet declaration.
+The user-defined facet is declared using the OPTIONAL `facets` facet in a type declaration. The value of the `facets` facet is a map. The key names the user-defined facet. The corresponding value defines the concrete value that the respective facet can take. The syntax of a [property declaration](#property-declarations) and user-defined facet declaration are the same. A facet restricts instances of a subtype, not its type, based on the concrete value defined in the facet declaration.
 
 Facet names MUST NOT begin with open parenthesis, to disambiguate the names from annotations. User-defined facet names on a type MUST NOT match built-in facets on that type, nor facet names of any ancestor type in the inheritance chain of the type.
 
@@ -1067,7 +1069,7 @@ A RAML processor must be able to determine the default type of a type declaratio
 
 ### Type Expressions
 
-Earlier, this specification used only simple type identifiers to refer to types, such as string, object, and Person. Type expressions provide a powerful way of referring to, and even defining, types. Type expressions can be used wherever a type is expected. The simplest type expression is just the name of a type. Using type expressions, you can devise type unions, arrays, maps, and other things.
+Type expressions provide a powerful way of referring to, and even defining, types. Type expressions can be used wherever a type is expected. The simplest type expression is just the name of a type. Using type expressions, you can devise type unions, arrays, maps, and other things.
 
 |Expression | Description |
 |:--------|:------------|
@@ -1270,11 +1272,11 @@ types:
       members: Person[] # invalid use of type expression '[]' and as a property type
 ```
 
-A RAML Processor MUST be able to interpret and apply JSON Schema and XML Schema.
+A RAML processor MUST be able to interpret and apply JSON Schema and XML Schema.
 
 An XML schema, or JSON schema, MUST NOT be used where the media type does not allow XML-formatted data, or JSON-formatted data, respectively. XML and JSON schemas are also forbidden in any declaration of query parameters, query string, URI parameters, and headers.
 
-The properties "schemas" and "types", as well as "schema" and "type", are mutually exclusive and synonymous for compatibility with RAML 0.8. API definitions should use "types" and "type", as "schemas" and "schema" are deprecated and might be removed in a future RAML version.
+The nodes "schemas" and "types", as well as "schema" and "type", are mutually exclusive and synonymous for compatibility with RAML 0.8. API definitions should use "types" and "type", as "schemas" and "schema" are deprecated and might be removed in a future RAML version.
 
 #### References to Inner Elements
 
@@ -1370,9 +1372,9 @@ It is highly RECOMMENDED that API documentation include a rich selection of exam
 
 #### Multiple Examples
 
-The OPTIONAL **examples** property can be used to attach multiple examples to a type declaration. Its value is a map of key-value pairs, where each key represents a unique identifier for an example and the value is a [single example](#single-example) property.
+The OPTIONAL **examples** facet can be used to attach multiple examples to a type declaration. Its value is a map of key-value pairs, where each key represents a unique identifier for an example and the value is a [single example](#single-example).
 
-The following example shows the value of an **examples** property:
+The following example shows the value of an **examples** facet:
 
 ```yaml
 message: # {key} - unique id
@@ -1387,7 +1389,7 @@ record: # {key} - unique id
 
 #### Single Example
 
-The OPTIONAL **example** property can be used to attach an example of a type instance to the type declaration. There are two ways to represent the example property value: as an explicit description of a specific type instance and as a map that contains additional facets.
+The OPTIONAL **example** facet can be used to attach an example of a type instance to the type declaration. There are two ways to represent the example facet value: as an explicit description of a specific type instance and as a map that contains additional facets.
 
 ##### As an explicit description of a specific type instance
 
@@ -1406,7 +1408,7 @@ The map can contain the following additional facets:
 |:--------|:------------|
 | displayName? | An alternate, human-friendly name for the example. If the example is part of an examples node, the default value is the unique identifier that is defined for this example.
 | description? | A substantial, human-friendly description for an example. Its value is a string and MAY be formatted using [markdown](#markdown).
-| (<annotationName>)? | [Annotations](#annotations) to be applied to this example. An annotation is a property having a key that begins with "(" and ends with ")". The text enclosed in parentheses is the annotation name.
+| (<annotationName>)? | [Annotations](#annotations) to be applied to this API. An annotation is a map having a key that begins with "(" and ends with ")" where the text enclosed in parentheses is the annotation name, and the value is an instance of that annotation.
 | value | The actual example of a type instance.
 | strict? | Validates the example against any type declaration (the default), or not. Set this to false avoid validation.
 
@@ -1536,9 +1538,9 @@ Key points about serialization are:
 
 ## Resources and Nested Resources
 
-A resource is identified by its relative URI, which MUST begin with a slash ("/"). Every property whose key begins with a slash, and is either at the root of the API definition or is the child property of a resource property, is such a resource property.
+A resource is identified by its relative URI, which MUST begin with a slash ("/"). Every node whose key begins with a slash, and is either at the root of the API definition or is the child node of a resource node, is such a resource node.
 
-A resource defined as a root-level property is called a top-level resource. The key of the root-level property is the URI of the resource relative to the baseUri if there is one. A resource defined as a child property of another resource is called a nested resource. The key of the child property is the URI of the nested resource relative to the parent resource URI.
+A resource defined as a root-level node is called a top-level resource. The key of the root-level node is the URI of the resource relative to the baseUri if there is one. A resource defined as a child node of another resource is called a nested resource. The key of the child node is the URI of the nested resource relative to the parent resource URI.
 
 This example shows an API definition with one top-level resource, /gists, and one nested resource, /public.
 
@@ -1553,7 +1555,7 @@ baseUri: https://api.github.com
     displayName: Public Gists
 ```
 
-The key of a resource property, its relative URI, MAY consist of multiple URI path fragments separated by slashes. For example, /bom/items might indicate the collection of items in a bill of materials as a single resource. However, if the individual URI path fragments are themselves resources, the API definition SHOULD use nested resources to describe this structure. For example, if /bom is itself a resource, then /items should be a nested resource of /bom, versus using /bom/items as a non-nested resource.
+The key of a resource node, its relative URI, MAY consist of multiple URI path fragments separated by slashes. For example, /bom/items might indicate the collection of items in a bill of materials as a single resource. However, if the individual URI path fragments are themselves resources, the API definition SHOULD use nested resources to describe this structure. For example, if /bom is itself a resource, then /items should be a nested resource of /bom, versus using /bom/items as a non-nested resource.
 
 Absolute URIs are not explicitly specified. They are computed by appending the relative URI of the top-level resource, and then successively appending the relative URI values for each nested resource until the target resource is reached. In this formation of the absolute URI, if a baseUri is defined, it is prepended before the relative URI of the top-level resource; any trailing slashes in the baseUri are removed before prepending.
 
@@ -1624,19 +1626,19 @@ The URIs in the following example would ALWAYS be ALLOWED.
 
 ### Resource Property
 
-The value of a resource property is an object whose properties are described in the following table.
+The value of a resource node is a map whose key-value pairs are described in the following table.
 
-|Property | Description |
+| Name | Description |
 |:--------|:------------|
-| displayName? | An alternate, human-friendly name for the resource. If the displayName property is not defined for a resource, documentation tools SHOULD refer to the resource by its property key, which acts as the resource name. For example, tools should refer to the relative URI /jobs.
+| displayName? | An alternate, human-friendly name for the resource. If the displayName node is not defined for a resource, documentation tools SHOULD refer to the resource by its key, which acts as the resource name. For example, tools should refer to the relative URI /jobs.
 | description? | A substantial, human-friendly description of a resource. Its value is a string and MAY be formatted using [markdown](#markdown).
-| (<annotationName>)? | [Annotations](#annotations) to be applied to this resource. An annotation is a property having a key that begins with "(" and ends with ")". The text enclosed in parentheses is the annotation name.
+| (<annotationName>)? | [Annotations](#annotations) to be applied to this API. An annotation is a map having a key that begins with "(" and ends with ")" where the text enclosed in parentheses is the annotation name, and the value is an instance of that annotation.
 | get?
      patch?
      put?
      post?
      delete?
      options?
      head? | The object describing the [method](#methods).
 | is? | A list of [traits to apply](#applying-resource-types-and-traits) to all methods declared (implicitly or explicitly) for this resource. Individual methods can override this declaration.
 | type? | The [resource type](#applying-resource-types-and-traits) that this resource inherits.
 | securedBy? | The [security schemes](#applying-security-schemes) that apply to all methods declared (implicitly or explicitly) for this resource.
 | uriParameters? | Detailed information about any URI parameters of this resource.
-| /<relativeUri>? | A nested resource, which is identified as any property whose name begins with a slash ("/"), and is therefore treated as a relative URI.
+| /<relativeUri>? | A nested resource, which is identified as any node whose name begins with a slash ("/"), and is therefore treated as a relative URI.
 
 ### Template URIs and URI Parameters
 
@@ -1653,11 +1655,11 @@ baseUri: https://app.zencoder.com/api/{version}
     description: A specific job, a member of the jobs collection
 ```
 
-The OPTIONAL **uriParameters** property, shown in the next example, is used to explicitly specify URI parameters in a [Template URI](#template-uri). The value of the uriParameters property is an object, specifically a [properties declaration](#property-declarations), as is the value of the properties object of a type declaration. Each property in the declaration object is a **URI parameter declaration**. Each property name corresponds to a parameter name in the [Template URI](#template-uri). Each property value specifies the URI parameter type as a type name or an inline type declaration.
+The OPTIONAL **uriParameters** node, shown in the next example, is used to explicitly specify URI parameters in a [Template URI](#template-uri). The value of the uriParameters node is a map, specifically a [properties declaration](#property-declarations), as is the value of the properties facet of a type declaration. Each property in the declaration object is a **URI parameter declaration**. Each property name corresponds to a parameter name in the [Template URI](#template-uri). Each property value specifies the URI parameter type as a type name or an inline type declaration.
 
-Every property in a uriParameters declaration MUST correspond exactly to the name of a URI parameter in the relative URI of the resource. All URI parameters in the relative URI do not need to be explicitly specified in the uriParameters property, but those that are not specified MUST be treated as a URI parameter of type string and required.
+Every property in a uriParameters declaration MUST correspond exactly to the name of a URI parameter in the relative URI of the resource. All URI parameters in the relative URI do not need to be explicitly specified in the uriParameters node, but those that are not specified MUST be treated as a URI parameter of type string and required.
 
-Like the [baseUriParameters root property](#base-uri-and-base-uri-parameters), the version parameter is a reserved parameter name in the uriParameters properties declaration. The version parameter value corresponds to the value of the version root-level property.
+Like the [baseUriParameters root node](#base-uri-and-base-uri-parameters), the version parameter is a reserved parameter name in the uriParameters properties declaration. The version parameter value corresponds to the value of the version root-level node.
 
 The following example shows two top-level resources, /user and /users, and a nested resource specified by its [Template URI](#template-uri), /{userId}. The URI parameter, userId, is explicitly declared and given a description and an integer type.
 
@@ -1718,7 +1720,7 @@ version: v1
 
 Although a URI parameter can be explicitly specified as optional, it SHOULD be required when surrounded directly by slashes ("/"). In this case, the URI parameter constitutes a complete URI path fragment, for example .../{objectId}/.... It usually makes no sense to allow a URI to contain adjacent slashes, enclosing no characters, for example ...//.... Hence, a URI parameter should be specified as optional only when it appears adjacent to other text. For example, /people/~{fieldSelectors} indicates that URI parameter {fieldSelectors} can be blank, and therefore optional, implying that /people/~ is a valid relative URI.
 
-A special URI reserved parameter, **ext**, might or might not be specified explicitly in a uriParameters property. Its meaning is reserved for use by a client to specify that the body of the request or response be of the associated media type.
+A special URI reserved parameter, **ext**, might or might not be specified explicitly in a uriParameters node. Its meaning is reserved for use by a client to specify that the body of the request or response be of the associated media type.
 
 |URI Parameter | Value |
 |:--------|:------------|
@@ -1739,25 +1741,25 @@ version: v1
 
 ## Methods
 
-RESTful API methods are operations that are performed on a resource. The OPTIONAL properties **get**, **patch**, **put**, **post**, **delete**, **head**, and **options** of a resource define its methods; these correspond to the HTTP methods defined in the HTTP version 1.1 specification [RFC2616](https://www.ietf.org/rfc/rfc2616.txt) and its extension, [RFC5789](https://tools.ietf.org/html/rfc5789). The value of these method properties is an object that has the following properties:
+RESTful API methods are operations that are performed on a resource. The OPTIONAL properties **get**, **patch**, **put**, **post**, **delete**, **head**, and **options** of a resource define its methods; these correspond to the HTTP methods defined in the HTTP version 1.1 specification [RFC2616](https://www.ietf.org/rfc/rfc2616.txt) and its extension, [RFC5789](https://tools.ietf.org/html/rfc5789). The value of these method properties is a map that has the following key-value pairs:
 
-|Property | Description |
+| Name | Description |
 |:--------|:------------|
-| displayName? | An alternate, human-friendly method name in the context of the resource. If the displayName property is not defined for a method, documentation tools SHOULD refer to the resource by its property key, which acts as the method name.
+| displayName? | An alternate, human-friendly method name in the context of the resource. If the displayName node is not defined for a method, documentation tools SHOULD refer to the resource by its key, which acts as the method name.
 | description? | A longer, human-friendly description of the method in the context of the resource. Its value is a string and MAY be formatted using [markdown](#markdown).
-| (<annotationName>)? | [Annotations](#annotations) to be applied to this method. An annotation is a property having a key that begins with "(" and ends with ")". The text enclosed in parentheses is the annotation name.
+| (<annotationName>)? | [Annotations](#annotations) to be applied to this API. An annotation is a map having a key that begins with "(" and ends with ")" where the text enclosed in parentheses is the annotation name, and the value is an instance of that annotation.
 | queryParameters? | Detailed information about any query parameters needed by this method. Mutually exclusive with queryString.
 | headers? | Detailed information about any request headers needed by this method.
 | queryString? | The query string needed by this method. Mutually exclusive with queryParameters.
 | responses? | Information about the expected responses to a request.
 | body? | A request body that the method admits.
-| protocols? | Explicitly specify the protocol(s) used to invoke a method, thereby overriding the protocols set elsewhere, for example in the baseUri or the [root-level protocols](#protocols) property.
+| protocols? | Explicitly specify the protocol(s) used to invoke a method, thereby overriding the protocols set elsewhere, for example in the baseUri or the [root-level protocols](#protocols) node.
 | is? | A list of the [traits](#applying-resource-types-and-traits) to apply to this method.
 | securedBy? | The [security schemes](#applying-security-schemes) that apply to this method.
 
 ### Headers
 
-An API's methods can support or require various HTTP headers. The OPTIONAL **headers** property is used to explicitly specify those headers. The value of the headers property is an object, specifically a [properties declaration](#property-declarations), as is the value of the properties object of a type declaration. Each property in this declaration object is a header **declaration**. Each property name specifies an allowed header name. Each property value specifies the header value type as a type name or an inline type declaration.
+An API's methods can support or require various HTTP headers. The OPTIONAL **headers** node is used to explicitly specify those headers. The value of the headers node is a map, specifically a [properties declaration](#property-declarations), as is the value of the properties object of a type declaration. Each property in this declaration object is a header **declaration**. Each property name specifies an allowed header name. Each property value specifies the header value type as a type name or an inline type declaration.
 
 The following simple example shows a post method with a single HTTP header named Zencoder-Api-Key of (implied) string type.
 
@@ -1823,11 +1825,11 @@ traits:
 
 ### Query Strings and Query Parameters
 
-An API method can support or require a query string in the URL on which the method is invoked. The query string in a URL is defined in [RFC3986](https://www.ietf.org/rfc/rfc3986.txt) as the part of the URL following the question mark separator ("?") and preceding any fragment ("#") separator. The query string can be specified either by the OPTIONAL **queryString** property or by the OPTIONAL **queryParameters** property. The queryString and queryParameters properties are mutually exclusive: processors MUST NOT allow both to be specified, explicitly or implicitly, on the same method of the same resource.
+An API method can support or require a query string in the URL on which the method is invoked. The query string in a URL is defined in [RFC3986](https://www.ietf.org/rfc/rfc3986.txt) as the part of the URL following the question mark separator ("?") and preceding any fragment ("#") separator. The query string can be specified either by the OPTIONAL **queryString** node or by the OPTIONAL **queryParameters** node. The queryString and queryParameters nodes are mutually exclusive: processors MUST NOT allow both to be specified, explicitly or implicitly, on the same method of the same resource.
 
 #### The Query String as a Whole
 
-The queryString property is used to specify the query string as a whole, rather than as name-value pairs. The queryString value is either the name of a data type or an inline data type declaration, including a data type expression. In either case, all types at the root of the type hierarchy of the data type MUST be either a scalar type or the object type, after fully expanding any union type expressions at every level of the type hierarchy.
+The **queryString** node is used to specify the query string as a whole, rather than as name-value pairs. The queryString value is either the name of a data type or an inline data type declaration, including a data type expression. In either case, all types at the root of the type hierarchy of the data type MUST be either a scalar type or the object type, after fully expanding any union type expressions at every level of the type hierarchy.
 
 If the type is derived from a scalar type, the query string as a whole MUST be described by the type.
 
@@ -1874,7 +1876,7 @@ types:
 
 #### Query Parameters in a Query String
 
-The queryParameters property specifies the set of query parameters from which the query string is composed. When applying the restrictions defined by the API, processors MUST regard the query string as a set of query parameters according to the URL encoding format. The value of the queryParameters property is a [properties declaration](#property-declarations) object, as is the value of the properties object of a type declaration. Each property in this declaration object is referred to as a **query parameter declaration**. Each property name specifies an allowed query parameter name. Each property value specifies the query parameter value type as the name of a type or an inline type declaration.
+The **queryParameters** node specifies the set of query parameters from which the query string is composed. When applying the restrictions defined by the API, processors MUST regard the query string as a set of query parameters according to the URL encoding format. The value of the queryParameters node is a [properties declaration](#property-declarations) object, as is the value of the properties object of a type declaration. Each property in this declaration object is referred to as a **query parameter declaration**. Each property name specifies an allowed query parameter name. Each property value specifies the query parameter value type as the name of a type or an inline type declaration.
 
 If a query parameter declaration specifies an array type for the value of the query parameter, processors MUST allow multiple instances of that query parameter in the request or response. In this case, the type of the elements of the array MUST be applied as the type of the value of query parameter instances.
 
@@ -1912,9 +1914,9 @@ baseUri: https://api.github.com/{version}
 
 ### Bodies
 
-The HTTP request **body** for a method is specified using the OPTIONAL body property. For example, to create a resource using a POST or PUT, the body of the request would usually include the details of the resource to be created.
+The HTTP request **body** for a method is specified using the OPTIONAL body node. For example, to create a resource using a POST or PUT, the body of the request would usually include the details of the resource to be created.
 
-The value of the body property is a **body declaration**. Generally, the body declaration is an object whose property names are the valid media types of the request body. Each property name MUST be a media type string conforming to the media type specification in [RFC6838](#https://tools.ietf.org/html/rfc6838). The property values are the corresponding data type declaration or data type name describing the request body. Alternatively, if [default media types](#default-media-type) have been declared at the root of the API, then the body declaration can consist of just the data type declaration or data type name describing the request body for that media type.
+The value of the body node is a "body declaration". Generally, the body declaration is a map whose key names are the valid media types of the request body. Each key name MUST be a media type string conforming to the media type specification in [RFC6838](#https://tools.ietf.org/html/rfc6838). The values are the corresponding data type declaration or data type name describing the request body. Alternatively, if [default media types](#default-media-type) have been declared at the root of the API, then the body declaration can consist of just the data type declaration or data type name describing the request body for that media type.
 
 The following example illustrates various combinations of both default and non-default media types, and both data type declarations and references.
 
@@ -1947,20 +1949,22 @@ types:
 
 The resources and methods sections of this document describe HTTP requests. This section describes the HTTP responses to method invocations on resources.
 
-The OPTIONAL **responses** property of a method on a resource describes the possible responses to invoking that method on that resource. The value of **responses** is an object that has properties named after possible HTTP status codes for that method on that resource. The property values describe the corresponding responses. Each value is a **response declaration**.
+The OPTIONAL **responses** node of a method on a resource describes the possible responses to invoking that method on that resource. The value of **responses** is a map where each key name represents that a possible HTTP status codes for that method on that resource. The values describe the corresponding responses. Each value is a [response declaration](#response-declaration).
 
-Properties of the responses object are often numeric, for example 200 or 204. Processors MUST treat these numeric keys as string keys in all situations. For example, '200' and 200 MUST be treated as duplicate property keys, and therefore, are not allowed simultaneously.
+Keys are often numeric, for example 200 or 204. Processors MUST treat these numeric keys as string keys in all situations. For example, '200' and 200 MUST be treated as duplicate  keys, and therefore, are not allowed simultaneously.
 
-The value of a response declaration is an object that can contain any of the following properties:
+### Response Declaration
 
-|Property | Description |
+The value of a response declaration is a map that can contain any of the following key-value pairs:
+
+| Name | Description |
 |:--------|:------------|
 | description? | A substantial, human-friendly description of a response. Its value is a string and MAY be formatted using [markdown](#markdown).
-| (<annotationName>) | [Annotations](#annotations) to be applied to this response. An annotation is a property having a key that begins with "(" and ends with ")". The text enclosed in parentheses is the annotation name.
+| (<annotationName>) | [Annotations](#annotations) to be applied to this API. An annotation is a map having a key that begins with "(" and ends with ")" where the text enclosed in parentheses is the annotation name, and the value is an instance of that annotation.
 | headers? | Detailed information about any response headers returned by this method
 | body? | The body of the response
 
-The syntax and semantics of the OPTIONAL properties **description**, **headers**, **body**, and **annotations** for responses and [method declarations](methods) are the same, but applied to HTTP responses rather than HTTP requests, respectively.
+The syntax and semantics of the OPTIONAL nodes **description**, **headers**, **body**, and **annotations** for responses and [method declarations](methods) are the same, but applied to HTTP responses rather than HTTP requests, respectively.
 
 The following example illustrates some possible responses:
 
@@ -2010,21 +2014,21 @@ There are many advantages of reusing patterns across multiple resources and meth
 
 Moreover, resource and method declarations are frequently repetitive. For example, an API that requires OAuth authentication might require an X-Access-Token header for all methods across all resources. For many reasons, it might be preferable to define such a pattern in a single place and apply it consistently everywhere.
 
-A resource type, like a resource, can specify security schemes, methods, and other properties. A resource that uses a resource type inherits its properties. A resource type can also use, and thus inherit from, another resource type. Resource types and resources are related through an inheritance chain pattern. A resource type definition MUST NOT incorporate nested resources. A resource type definition cannot be used to generate nested resources when the definition is applied to a resource. A resource type definition does not apply to its own existing nested resources.
+A resource type, like a resource, can specify security schemes, methods, and other nodes. A resource that uses a resource type inherits its nodes. A resource type can also use, and thus inherit from, another resource type. Resource types and resources are related through an inheritance chain pattern. A resource type definition MUST NOT incorporate nested resources. A resource type definition cannot be used to generate nested resources when the definition is applied to a resource. A resource type definition does not apply to its own existing nested resources.
 
-A trait, like a method, can provide method-level properties such as description, headers, query string parameters, and responses. Methods that use one or more traits inherit properties of those traits. A resource and resource type can also use, and thus inherit from, one or more traits, which then apply to all methods of the resource and resource type. Traits are related to methods through a mixing pattern.
+A trait, like a method, can provide method-level nodes such as description, headers, query string parameters, and responses. Methods that use one or more traits inherit nodes of those traits. A resource and resource type can also use, and thus inherit from, one or more traits, which then apply to all methods of the resource and resource type. Traits are related to methods through a mixing pattern.
 
 ### Declaration Resource Types and Traits
 
-Resource types can be declared using the OPTIONAL **resourceTypes** property at the root of the API definition. The value of this property is an object. Its property names become names of resource types that can be referenced throughout the API. Its property values are resource type declarations.
+Resource types can be declared using the OPTIONAL **resourceTypes** node at the root of the API definition. The value of this node is a map where keys names become names of resource types that can be referenced throughout the API, and values are resource type declarations.
 
-Similarly, traits can be declared using the OPTIONAL **traits** property at the root of the API definition. The value of this property is an object. Its property names become names of traits that can be referenced throughout the API. Its property values are trait declarations.
+Similarly, traits can be declared using the OPTIONAL **traits** node at the root of the API definition. The value of this node is a map where key names become names of traits that can be referenced throughout the API, and values are trait declarations.
 
-Resource type and trait declarations can have the following properties, in addition to all the properties that resources and methods can have, respectively (except that resource type declarations MUST NOT have nested resource properties).
+Resource type and trait declarations can have the following nodes, in addition to all the nodes that resources and methods can have, respectively (except that resource type declarations MUST NOT have nested resource nodes).
 
-| Property | Definition |
+| Name | Definition |
 |:---------|:-----------|
-| usage? | The OPTIONAL **usage** property of a resource type or trait provides instructions about how and when the resource type or trait should be used. Documentation generators MUST describe this property in terms of the characteristics of the resource and method, respectively. However, the resources and methods MUST NOT inherit the usage property. Neither resources nor methods allow a property named usage.
+| usage? | The OPTIONAL **usage** node of a resource type or trait provides instructions about how and when the resource type or trait should be used. Documentation generators MUST describe this node in terms of the characteristics of the resource and method, respectively. However, the resources and methods MUST NOT inherit the usage node. Neither resources nor methods allow a node named usage.
 
 The following example illustrates the declaration of several resource types and traits:
 
@@ -2078,9 +2082,9 @@ resourceTypes:
 
 ### Applying Resource Types and Traits
 
-A resource can specify the resource type from which it is derived using the OPTIONAL **type** property. The resource type MUST be the name of a resource type defined within the root-level resourceTypes property or in a library. Resource type definitions do not apply to existing nested resources.
+A resource can specify the resource type from which it is derived using the OPTIONAL **type** node. The value MUST be the name of a resource type defined within the root-level resourceTypes node or in a library. Resource type definitions do not apply to existing nested resources.
 
-Similarly, a method can specify one or more traits it inherits using the OPTIONAL **is** property. The value of a trait is an array of any number of elements where each MUST be the name of a trait defined within the root-level traits property or in a library. A trait can also be applied to a resource by using the **is** property. Using this property is equivalent to applying the trait to all methods for that resource, whether declared explicitly in the resource definition or inherited from a resource type. A trait is applied to a method in left-to-right order, according to the traits defined in the **is** property. Trait definitions do not apply to nested resources.
+Similarly, a method can specify one or more traits it inherits using the OPTIONAL **is** node. The value of a trait is an array of any number of elements where each MUST be the name of a trait defined within the root-level traits node or in a library. A trait can also be applied to a resource by using the **is** node. Using this node is equivalent to applying the trait to all methods for that resource, whether declared explicitly in the resource definition or inherited from a resource type. A trait is applied to a method in left-to-right order, according to the traits defined in the **is** node. Trait definitions do not apply to nested resources.
 
 The following example illustrates the application of resource types and traits.
 
@@ -2220,9 +2224,9 @@ When defining resource types, it can be useful to capture patterns that manifest
 To accommodate this need, a resource type definition MAY append a question mark ("?") suffix to the name of any method to declare the method as optional, resulting in the following behavior:
 
 * Do not apply the method to the resource if it doesn't already exist at the corresponding level in the resource.
-* Apply the value of the method property to the resource type if the method name without the question mark is already defined, explicitly or implicitly, at the corresponding level in the resource.
+* Apply the value of the method node to the resource type if the method name without the question mark is already defined, explicitly or implicitly, at the corresponding level in the resource.
 
-The following example shows a resource type called corpResource with an optional post? property that defines a required header called X-Chargeback and a custom parameter called TextAboutPost. The inheriting resource /servers defines a post method, so it needs to include the X-Chargeback header requirement. TextAboutPost MUST be defined as well. The inheriting resource /queues does not define a post method, so it does not have to define the X-Chargeback header or the TextAboutPost parameter.
+The following example shows a resource type called corpResource with an optional post? node that defines a required header called X-Chargeback and a custom parameter called TextAboutPost. The inheriting resource /servers defines a post method, so it needs to include the X-Chargeback header requirement. TextAboutPost MUST be defined as well. The inheriting resource /queues does not define a post method, so it does not have to define the X-Chargeback header or the TextAboutPost parameter.
 
 ```yaml
 #%RAML 1.0
@@ -2383,24 +2387,26 @@ RAML supports the following built-in security scheme types:
 
 A processing application developer MAY provide support for these mechanisms. If a mechanism is supported, it MUST conform to the specified standard.
 
-Additionally, any security scheme definition may be augmented with a describedBy property, which allows the designer to document the API security scheme.
+Additionally, any security scheme definition may be augmented with a describedBy node, which allows the designer to document the API security scheme.
 
 ### Security Scheme Declaration
 
-The security scheme is declared using the following properties:
+The security scheme node is a map that has the following key-value pairs:
 
-|Property   |Description|
+|Name   |Description|
 |:----------|:----------|
-| type | The security schemes property that MUST be used to specify the API security mechanisms, including the required settings and the authentication methods that the API supports. One API-supported authentication method is allowed. The value MUST be one of the following methods: OAuth 1.0, OAuth 2.0, Basic Authentication, Digest Authentication, Pass Through, x-<other>
+| type | Specifies the API security mechanisms. One API-supported authentication method is allowed. The value MUST be one of the following methods: OAuth 1.0, OAuth 2.0, Basic Authentication, Digest Authentication, Pass Through, x-<other>
 | displayName? | An alternate, human-friendly name for the security scheme.
 | description? | Information that MAY be used to describe a security scheme. Its value is a string and MAY be formatted using [markdown](#markdown).
-| [describedBy?](#describedby) | A description of the following security-related request components determined by the scheme: the headers, query parameters, or responses. As a best practice, even for standard security schemes, API designers SHOULD describe these properties of security schemes. Including the security scheme description completes the API documentation.
+| [describedBy?](#describedby) | A description of the following security-related request components determined by the scheme: the headers, query parameters, or responses. As a best practice, even for standard security schemes, API designers SHOULD describe these nodes of security schemes. Including the security scheme description completes the API documentation.
 | settings? | The [settings](#settings) attribute MAY be used to provide security scheme-specific information.
 
-An optional **securitySchemes** property is defined for the RAML document root. The value of securitySchemes is an object having properties that map security scheme names to security scheme declarations.
-Each authentication pattern supported by the API must be expressed as a component of the **securitySchemes** property value.
+An optional **securitySchemes** node is defined for the RAML document root. The value of securitySchemes is a map having key-value pairs that map security scheme names to security scheme declarations.
+
+Each authentication pattern supported by the API must be expressed as a component of the **securitySchemes** node value.
 
 In this example, the Dropbox API supports authentication using OAuth 2.0 and OAuth 1.0:
+
 ```yaml
 #%RAML 1.0
 title: Dropbox API
@@ -2450,32 +2456,32 @@ securitySchemes:
 
 #### describedBy
 
-The value of the **describedBy** property is defined as follows:
+The value of the **describedBy** node is defined as a map with the following key-value pairs as follows:
 
-|Property   |Description|
+|Name   |Description|
 |:----------|:----------|
 | headers? | Optional array of [Headers](#headers), documenting the possible headers that could be accepted.
 | queryParameters? | Query parameters, used by the schema to authorize the request. Mutually exclusive with [queryString](#query-strings-and-query-parameters).
 | queryString? | The query string used by the schema to authorize the request. Mutually exclusive with [queryParameters](#query-strings-and-query-parameters).
 | responses? | An optional array of [responses](#responses), representing the possible responses that could be sent.
-| (<annotationName>)? | [Annotations](#annotations) to be applied to this part of the security scheme. An annotation is a property having a key that begins with "(" and ends with ")". The text enclosed in parentheses is the annotation name.
+| (<annotationName>)? | [Annotations](#annotations) to be applied to this API. An annotation is a map having a key that begins with "(" and ends with ")" where the text enclosed in parentheses is the annotation name, and the value is an instance of that annotation.
 
 #### Settings
 
-The settings attribute MAY be used to provide security scheme-specific information. The required attributes vary depending on which type of security scheme is declared.
+The **settings** node MAY be used to provide security scheme-specific information. The required nodes vary depending on which type of security scheme is declared.
 
-The settings attribute describes the minimum set of properties that any processing application MUST provide and validate if it chooses to implement the security scheme. Processing applications MAY choose to recognize other properties for token lifetime, preferred cryptographic algorithms, and other things.
+The settings node describes the minimum set of properties that any processing application MUST provide and validate if it chooses to implement the security scheme. Processing applications MAY choose to recognize other properties for token lifetime, preferred cryptographic algorithms, and other things.
 
 ##### OAuth 1.0
 
-Security schemes of this type have the following properties:
+Security schemes of this type have the following nodes:
 
-|Property |Description |
+|Name |Description |
 |:--------|:------------|
 | requestTokenUri | The URI of the *Temporary Credential Request endpoint* as defined in [RFC5849 Section 2.1](https://tools.ietf.org/html/rfc5849#section-2.1)
 | authorizationUri | The URI of the *Resource Owner Authorization endpoint* as defined in [RFC5849 Section 2.2](https://tools.ietf.org/html/rfc5849#section-2.2)
 | tokenCredentialsUri | The URI of the *Token Request endpoint* as defined in [RFC5849 Section 2.3](https://tools.ietf.org/html/rfc5849#section-2.3)
-| signatures | A list of signature methods used by the Authorization server, which can be any of the following: `HMAC-SHA1`, `RSA-SHA1`, or `PLAINTEXT`. If this property is missing, it is assumed that the Authentication server allows any signature method defined in [RFC5849 Section 3.4](https://tools.ietf.org/html/rfc5849#section-3.4).
+| signatures | A list of signature methods used by the Authorization server, which can be any of the following: `HMAC-SHA1`, `RSA-SHA1`, or `PLAINTEXT`. If signatures is missing, it is assumed that the Authentication server allows any signature method defined in [RFC5849 Section 3.4](https://tools.ietf.org/html/rfc5849#section-3.4).
 
 OAuth 1.0 authentication follows the standard described in [RFC5849](https://tools.ietf.org/html/rfc5849). The following example shows how to set OAuth 1.0 properties:
 
@@ -2496,9 +2502,9 @@ securitySchemes:
 
 ##### OAuth 2.0
 
-Security schemes of this type have the following properties:
+Security schemes of this type have the following nodes:
 
-|Property |Description |
+| Name |Description |
 |:--------|:------------|
 |authorizationUri| The URI of the *Authorization Endpoint* as defined in [RFC6749 Section 3.1](https://tools.ietf.org/html/rfc6749#section-3.1). Providing an Authorization Endpoint is only mandatory using either the `authorization_code` or `implicit` grant type. It is not mandatory for any other.
 |accessTokenUri| The URI of the *Token Endpoint* as defined in [RFC6749 Section 3.2](https://tools.ietf.org/html/rfc6749#section-3.2).
@@ -2630,11 +2636,11 @@ securitySchemes:
 
 #### Applying Security Schemes
 
-The **securedBy** attribute in the RAML document root can apply security schemes to every method of the API. All API methods, except those having their own securedBy attribute, can be authenticated by any of the specified security schemes.
+The **securedBy** node in the RAML document root can apply security schemes to every method of the API. All API methods, except those having their own securedBy node, can be authenticated by any of the specified security schemes.
 
-Applying a security scheme to a method overrides any security scheme applied to the API as a whole. To indicate that a method is protected using a specific security scheme, the method MUST be defined by using the **securedBy** attribute.
+Applying a security scheme to a method overrides any security scheme applied to the API as a whole. To indicate that a method is protected using a specific security scheme, the method MUST be defined by using the **securedBy** node.
 
-The value assigned to the securedBy attribute MUST be a list of any of the security schemes previously defined in the **securitySchemes** property of RAML document root.
+The value assigned to the securedBy node MUST be a list of any of the security schemes previously defined in the **securitySchemes** node of RAML document root.
 
 ```yaml
 #%RAML 1.0
@@ -2650,7 +2656,7 @@ securitySchemes:
     securedBy: [oauth_2_0, oauth_1_0]
 ```
 
-A securedBy attribute containing null as the array component indicates the method can be called without applying any security scheme.
+A securedBy node containing null as the array component indicates the method can be called without applying any security scheme.
 
 ```yaml
 #%RAML 1.0
@@ -2664,11 +2670,11 @@ securitySchemes:
     securedBy: [null, oauth_2_0]
 ```
 
-The **securedBy** attribute can also apply a list of security schemes to a resource. All resource methods, except those having their own securedBy attribute, can be authenticated by any of the specified security schemes. The value of the resources attribute overrides that of the root attribute. Security schemes applied to a resource MUST NOT incorporate nested resources; security schemes do not apply to existing nested resources.
+The **securedBy** node can also apply a list of security schemes to a resource. All resource methods, except those having their own securedBy node, can be authenticated by any of the specified security schemes. The value of the resources node overrides that of the root attribute. Security schemes applied to a resource MUST NOT incorporate nested resources; security schemes do not apply to existing nested resources.
 
 Applying a security scheme to a method overrides security schemes applied to the API and to resources having the method as a sibling.
 
-If the processing application supports custom properties, custom parameters can be provided to the security scheme at the moment of inclusion in a method.
+If the processing application supports custom nodes, custom parameters can be provided to the security scheme at the moment of inclusion in a method.
 
 The following example assigns a value to the parameter **scopes**:
 
@@ -2688,9 +2694,9 @@ The list of required and optional parameters to be provided to the security sche
 
 ## Annotations
 
-Annotations provide a mechanism to extend the API specification with metadata beyond the metadata already defined in this RAML 1.0 specification. Annotations can also be used to add properties to the built-in RAML properties in certain locations within the RAML specification. Processors MAY support certain annotations to add additional specificity to the API description, enable tooling such as testing, support API repositories and API discovery, and so on. Processors MAY ignore any and all annotations.
+Annotations provide a mechanism to extend the API specification with metadata beyond the metadata already defined in this RAML 1.0 specification. Annotations can also be used to add properties to the built-in RAML nodes in certain locations within the RAML specification. Processors MAY support certain annotations to add additional specificity to the API description, enable tooling such as testing, support API repositories and API discovery, and so on. Processors MAY ignore any and all annotations.
 
-Annotations used in an API specification MUST be declared in a root-level annotationTypes property. Annotations can have values, which are defined and constrained in annotation type declarations. Processors can then rely on the declarations to ensure annotation values meet expectations.
+Annotations used in an API specification MUST be declared in a root-level annotationTypes node. Annotations can have values, which are defined and constrained in annotation type declarations. Processors can then rely on the declarations to ensure annotation values meet expectations.
 
 The following example shows various annotation type declarations and the application of the annotations to an API definition.
 
@@ -2734,27 +2740,27 @@ Annotations applied to a data type are not inherited when that data type is inhe
 
 ### Declaring Annotation Types
 
-Annotation types are declared using the OPTIONAL root-level **annotationTypes** property. The value of the annotationsType property is an object whose keys define annotation type names, also referred to as annotations, and whose values are objects called annotation type declarations. An annotation type declaration has the same syntax as a data type declaration, and its facets have the same syntax as the corresponding ones for data types, but with the addition of the allowedTargets facet. An annotation type declaration constrains the value of an annotation of that type just as a data type declaration constrains the value of a URI parameter, query parameter, header, or body of that type. The allowedTargets facet restricts the kinds of locations where the annotation can be applied. Annotation types, like data types, can extend other data types, but annotation types themselves can neither be extended nor used anywhere data types can be used.
+Annotation types are declared using the OPTIONAL root-level **annotationTypes** node. The value of the annotationsType node is a map whose keys define annotation type names, also referred to as annotations, and whose values are key-value pairs called annotation type declarations. An annotation type declaration has the same syntax as a data type declaration, and its facets have the same syntax as the corresponding ones for data types, but with the addition of the allowedTargets facet. An annotation type declaration constrains the value of an annotation of that type just as a data type declaration constrains the value of a URI parameter, query parameter, header, or body of that type. The allowedTargets node restricts the kinds of locations where the annotation can be applied. Annotation types, like data types, can extend other data types, but annotation types themselves can neither be extended nor used anywhere data types can be used.
 
-|Property |Description |
+|Name |Description |
 |:--------|:------------|
-| displayName? | A friendly name used only for display or documentation purposes. The default is the element key, the name of the property itself.
+| displayName? | A friendly name used only for display or documentation purposes. The default is the element key, the name of the annotation itself.
 | description? | The intended use or meaning of an annotation. A string that MAY be formatted using [markdown](#markdown).
-| (<annotationName>)? | [Annotations](#annotations) to be applied to this annotation type. An annotation is a property having a key that begins with "(" and ends with ")". The text enclosed in parentheses is the annotation name.
-| allowedTargets? | The locations to which annotations are restricted. If this property is specified, annotations of this type may be applied only on a property corresponding to one of the locations. The value MUST be one or more of the options described in the [Target Locations](#annotation-target-location).
+| (<annotationName>)? | [Annotations](#annotations) to be applied to this API. An annotation is a map having a key that begins with "(" and ends with ")" where the text enclosed in parentheses is the annotation name, and the value is an instance of that annotation.
+| allowedTargets? | The locations to which annotations are restricted. If this node is specified, annotations of this type may be applied only on a node corresponding to one of the locations. The value MUST be one or more of the options described in the [Target Locations](#annotation-target-location).
 
 If an annotation type declaration specifies neither a type facet nor a properties facet, the default annotationName type is string.
 
-All annotations used in an API specification MUST be declared in its annotationTypes property. Any value of an annotation MUST be valid according to its annotation type.
+All annotations used in an API specification MUST be declared in its annotationTypes node. Any value of an annotation MUST be valid according to its annotation type.
 
-If the allowedTargets property is not present, the annotation can be applied in any of the target locations listed in the Target Locations table. If the allowedTargets property is present, it restricts where the annotation can be applied, as described in [Annotation Targets](#annotation-targets).
+If the allowedTargets node is not present, the annotation can be applied in any of the target locations listed in the Target Locations table. If the allowedTargets node is present, it restricts where the annotation can be applied, as described in [Annotation Targets](#annotation-targets).
 
 
 ### Applying Annotations
 
 To be applied in an API specification, the annotation MUST be declared in an annotation type.
 
-A declared annotation can be applied to an object in the specification by adding a property on that object whose key is the name of the annotation type enclosed in parentheses. The annotation value MUST be valid according to the corresponding annotation type.
+A declared annotation can be applied to a node in the specification by adding an annotation node on that whose key is the name of the annotation type enclosed in parentheses. The annotation value MUST be valid according to the corresponding annotation type.
 
 The example below, a small subset of the previous example, shows an explicit declaration and use of a testHarness annotation that should be a string value.
 
@@ -2847,7 +2853,7 @@ extends
 
 #### Annotation Targets
 
-The location within an API specification where annotations can be applied MUST be one of the target locations in the following Target Locations table. The targets are the locations themselves, not sub-properties within the locations; for example, the Method target refers to the method property, not to the method display name, description, and so on.
+The location within an API specification where annotations can be applied MUST be one of the target locations in the following Target Locations table. The targets are the locations themselves, not sub-properties within the locations; for example, the Method target refers to the method node, not to the method display name, description, and so on.
 
 
 
@@ -2856,19 +2862,19 @@ The location within an API specification where annotations can be applied MUST b
 |Target | Description |
 |:--------|:------------|
 | API | The root of a RAML document
-| DocumentationItem | An item in the collection of items that is the value of the root-level documentation property
-| Resource | A resource (relative URI) property, root-level or nested
-| Method | A method property
-| Response | A property of the responses property, whose key is an HTTP status code
-| RequestBody | The body property of a method
-| ResponseBody | The body property of a response
+| DocumentationItem | An item in the collection of items that is the value of the root-level documentation node
+| Resource | A resource (relative URI) node, root-level or nested
+| Method | A method node
+| Response | A declaration of the responses node, whose key is an HTTP status code
+| RequestBody | The body node of a method
+| ResponseBody | The body node of a response
 | TypeDeclaration | A data type declaration (inline or in a global types collection), header declaration, query parameter declaration, URI parameter declaration, or a property within any of these declarations, where the type property can be used
-| Example | Either an example or examples property
-| ResourceType | A resource type property
-| Trait | A trait property
+| Example | Either an example or examples node
+| ResourceType | A resource type node
+| Trait | A trait node
 | SecurityScheme | A security scheme declaration
-| SecuritySchemeSettings | The settings property of a security scheme declaration
-| AnnotationType | A property of the annotationTypes property, whose key is a name of an annotation type and whose value describes the annotation
+| SecuritySchemeSettings | The settings node of a security scheme declaration
+| AnnotationType | A declaration of the annotationTypes node, whose key is a name of an annotation type and whose value describes the annotation
 | Library | The root of a library
 | Overlay | The root of an overlay
 | Extension | The root of an extension
@@ -2913,9 +2919,9 @@ RAML provides several mechanisms to help modularize the ecosystem of an API spec
 
 ### Includes
 
-RAML processors MUST support the OPTIONAL **!include** tag, which specifies the inclusion of external files into the API specification. Being a YAML tag, the exclamation point ("!") prefix is required. In an API specification, the !include tag is located only in a property value position. The !include tag MUST be the value of a property, which assigns the contents of the file named by the !include tag to the value of the property.
+RAML processors MUST support the OPTIONAL **!include** tag, which specifies the inclusion of external files into the API specification. Being a YAML tag, the exclamation point ("!") prefix is required. In an API specification, the !include tag is located only in a node value position. The !include tag MUST be the value of a node, which assigns the contents of the file named by the !include tag to the value of the node.
 
-In the following example, the set of types to be used in the API specification is retrieved from a file called myTypes.raml and used as the value of the types property.
+In the following example, the set of types to be used in the API specification is retrieved from a file called myTypes.raml and used as the value of the types node.
 
 ```yaml
 #%RAML 1.0
@@ -2941,9 +2947,9 @@ A file to be included MAY begin with a RAML fragment identifier line, which cons
 
 |Fragment Identifier | Description | Relevant RAML Specification Section |
 |:-------------------|:------------| :-----------------------------------|
-| DocumentationItem | An item in the collection of items that is the value of the root-level documentation property | [User Documentation](#user-documentation)
-| DataType | A data type declaration where the type property may be used | [Types](#types)
-| NamedExample | A property of the examples property, whose key is a name of an example and whose value describes the example | [Examples](#defining-examples-in-raml)
+| DocumentationItem | An item in the collection of items that is the value of the root-level documentation node | [User Documentation](#user-documentation)
+| DataType | A data type declaration where the type node may be used | [Types](#types)
+| NamedExample | A declaration of the examples facet, whose key is a name of an example and whose value describes the example | [Examples](#defining-examples-in-raml)
 | ResourceType | A single resource type declaration | [Resource Types and Traits](#resource-types-and-traits)
 | Trait | A single trait declaration | [Resource Types and Traits](#resource-types-and-traits)
 | AnnotationTypeDeclaration | A single annotation type declaration | [Annotations](#annotations)
@@ -3086,11 +3092,11 @@ traits:
 
 RAML libraries are used to combine any collection of data type declarations, resource type declarations, trait declarations, and security scheme declarations into modular, externalized, reusable groups. While libraries are intended to define common declarations in external documents, which are then included where needed, libraries can also be defined inline.
 
-The following table describes the properties, which are optional, of a library object.
+The following table describes the nodes, which are optional, of a library node.
 
-|Property | Description |
+|Name | Description |
 |:--------|:------------|
-| types?
      schemas?
      resourceTypes?
      traits?
      securitySchemes?
      annotationTypes?
      (<annotationName>)?
      uses? | The definition of each property is the same as that of the corresponding property at the root of a RAML document. A library supports annotation properties like any other RAML document.
+| types?
      schemas?
      resourceTypes?
      traits?
      securitySchemes?
      annotationTypes?
      (<annotationName>)?
      uses? | The definition of each node is the same as that of the corresponding node at the root of a RAML document. A library supports annotation node like any other RAML document.
 | usage | Describes the content or purpose of a specific library. The value is a string and MAY be formatted using [markdown](#markdown).
 
 The following example shows a simple library as a standalone, reusable RAML fragment document.
@@ -3119,9 +3125,9 @@ resourceTypes:
 
 #### Applying Libraries
 
-Any number of libraries can be applied by using the OPTIONAL **uses** property ONLY at the root of a ["master"] RAML or RAML fragment file. The value of the uses property is a map of key-value pairs. The keys are treated as library names, or namespaces, and the value MUST be the location of a RAML library file, usually an external RAML library fragment document.
+Any number of libraries can be applied by using the OPTIONAL **uses** node ONLY at the root of a ["master"] RAML or RAML fragment file. The value of the uses node is a map of key-value pairs. The keys are treated as library names, or namespaces, and the value MUST be the location of a RAML library file, usually an external RAML library fragment document.
 
-In the document that applies a library, the data types, resource types, traits, security schemes, and annotation types in the library become available from the document. The assets in the library are referenced from the document using dot notation as follows: concatenate the library name followed by a period ("."), and then the name of the data type, resource type, trait, security scheme, or annotation type. The library name defines a namespace for the library objects within the context that the library is applied. Namespaces defined in a **uses** statement in a specific file are only consumable within that file and serve only to disambiguate the included libraries from each other. Therefore, any processor MUST not allow any composition of namespaces using "." across multiple libraries.
+In the document that applies a library, the data types, resource types, traits, security schemes, and annotation types in the library become available from the document. The assets in the library are referenced from the document using dot notation as follows: concatenate the library name followed by a period ("."), and then the name of the data type, resource type, trait, security scheme, or annotation type. The library name defines a namespace for the library nodes within the context that the library is applied. Namespaces defined in a **uses** statement in a specific file are only consumable within that file and serve only to disambiguate the included libraries from each other. Therefore, any processor MUST not allow any composition of namespaces using "." across multiple libraries.
 
 Using **uses** does NOT automatically import the remote library assets into the local file, but the local file can import those assets by referring to the assets from its contents. For example, a RAML type fragment file that uses a library of remote types can import one of those types by referring to it. The remote type is included as if it were defined locally within the RAML type fragment file.
 
@@ -3192,7 +3198,7 @@ get:
 
 API definitions might need to be extended in a variety of ways for different needs. Annotations extend an API by adding metadata beyond that which is standardized in this RAML specification. Overlays of standard or non-standard metadata on top of an existing API definition can specify implementation details, or provide a translation of human-oriented documentation into different languages, without changing API behavior. Extending an API definition by adding to its behavior, or overriding certain aspects, is another way to satisfy different needs. RAML provides two mechanisms for extending API definitions: overlays and extensions.
 
-Overlays and extensions are RAML documents that add or override properties of a RAML API definition. The first line of an overlay or extension document MUST begin with the text _#%RAML 1.0 Overlay_ or _#%RAML 1.0 Extension_, respectively, followed by nothing but the end of the line. An overlay or extension document MUST contain a root-level `extends` property whose value MUST be the location of a valid RAML API definition or another overlay or extension; the location specification is an absolute or relative path, or a URL, equivalent to an [!include tag argument](#includes). The document specified in the `extends` property is called the master RAML document.
+Overlays and extensions are RAML documents that add or override nodes of a RAML API definition. The first line of an overlay or extension document MUST begin with the text _#%RAML 1.0 Overlay_ or _#%RAML 1.0 Extension_, respectively, followed by nothing but the end of the line. An overlay or extension document MUST contain a root-level `extends` node whose value MUST be the location of a valid RAML API definition or another overlay or extension; the location specification is an absolute or relative path, or a URL, equivalent to an [!include tag argument](#includes). The document specified in the `extends` node is called the master RAML document.
 
 The remainder of an overlay or extension document follows the same rules as a RAML API definition, but with certain [restrictions](#overlays) in case of an overlay.
 
@@ -3207,22 +3213,22 @@ To apply any combination of overlays and/or extensions, all must share the same
 
 #### Overlays
 
-An overlay adds or overrides properties of a RAML API definition while preserving its behavioral, functional aspects. Certain properties of a RAML API definition specify the behavior of an API: its resources, methods, parameters, bodies, responses, and so on. These properties cannot be changed by applying an overlay. In contrast, other properties, such as descriptions or annotations, address concerns beyond the functional interface, such as the human-oriented descriptive documentation in some language, or implementation or verification information for use in automated tools. These properties can be changed by applying an overlay.
+An overlay adds or overrides nodes of a RAML API definition while preserving its behavioral, functional aspects. Certain nodes of a RAML API definition specify the behavior of an API: its resources, methods, parameters, bodies, responses, and so on. These nodes cannot be changed by applying an overlay. In contrast, other nodes, such as descriptions or annotations, address concerns beyond the functional interface, such as the human-oriented descriptive documentation in some language, or implementation or verification information for use in automated tools. These nodes can be changed by applying an overlay.
 
 Overlays are particularly important for separating interface from implementation. Overlays enable separate lifecycles for the behavioral aspects of the API that need to be controlled tightly, such as a contract between the API provider and its consumers, versus those needing little control, such as the human- or implementation-oriented aspects that can evolve at different paces. For example, adding hooks for testing and monitoring tools, appending metadata relevant to a registry of APIs, or providing updated or translated human documentation can be achieved without changing any aspects of the behavioral aspects of the API. These things can be controlled through a rigorous version and change management process.
 
 It is difficult to draw a definitive line between the behavioral and implementation-oriented aspects of the API because, for example, some semantics of the API are often captured only in human documentation. RAML does, however, define the specific behavior-invariance restrictions on overlay files that processors MUST follow. Processors can then choose to offer the master API definition as well as its modifications after applying one or more overlays, so the consumer can benefit from all the information available. For example, if overlay files are provided as a means of localizing textual descriptions of resources, methods, and data, the consumer of generated documentation can be offered a choice of which localized overlays to apply.
 
-The behavior-invariance restrictions of an overlay are defined as follows: after applying the [merging algorithm](#merging-rules) and before applying any inheritances of types, resource types, traits, and annotation types, the tree of nodes in the merged document is compared with the tree of nodes in the master RAML document after resolving all !include tags. Any differences in the documents MUST be only in the properties listed in the following table.
+The behavior-invariance restrictions of an overlay are defined as follows: after applying the [merging algorithm](#merging-rules) and before applying any inheritances of types, resource types, traits, and annotation types, the tree of nodes in the merged document is compared with the tree of nodes in the master RAML document after resolving all !include tags. Any differences in the documents MUST be only in the nodes listed in the following table.
 
-|Property | Allowed differences |
+|Name | Allowed differences |
 |:--------|:------------|
-| title
      description
      documentation
      usage
      example | The merged tree can include new properties of this type or properties with different values from those in the master tree.
+| title
      description
      documentation
      usage
      example | The merged tree can include new nodes of this type or nodes with different values from those in the master tree.
 | types | In addition to allowed differences described elsewhere in this table, the merged tree can also include new data types.
 | annotationTypes | The merged tree can include new annotation types or new values for existing annotation types, as long as all annotations in the merged API definition validate against the annotation types in the merged tree.
-| any annotation property | The merged tree can include new annotations of annotation types declared in the merged tree, or annotations with different values from those in the master tree.
+| any annotation node | The merged tree can include new annotations of annotation types declared in the merged tree, or annotations with different values from those in the master tree.
 | examples | The merged tree can contain new named examples, or named examples with different values from those in the master tree.
-| documentation | The merged tree can contain new items in the array that is the value of the documentation root-level property. To change or remove existing items, the documentation property itself can be overridden in the overlay.
+| documentation | The merged tree can contain new items in the array that is the value of the documentation root-level node. To change or remove existing items, the documentation node itself can be overridden in the overlay.
 
 The following example illustrates a very simple RAML definition of a library books API, along with overlay files that provide a Spanish translation and metadata for an API monitoring service.
 
@@ -3277,7 +3283,7 @@ annotationTypes:
 
 #### Extensions
 
-An extension broadens a RAML API definition by adding to, or modifying aspects of its behavior and other functionality. An extension can be useful in separating a core, broadly-available API from layers of functionality available to more restricted audiences, for creating variants of an API for somewhat different purposes, or for specifying instance-specific properties of an API, such as its service endpoint (URL) without altering its pure interface definition document.
+An extension broadens a RAML API definition by adding to, or modifying aspects of its behavior and other functionality. An extension can be useful in separating a core, broadly-available API from layers of functionality available to more restricted audiences, for creating variants of an API for somewhat different purposes, or for specifying instance-specific nodes of an API, such as its service endpoint (URL) without altering its pure interface definition document.
 
 The following examples build on examples in the Overlays section by adding an extension for admins to add book items to a collection, adding an overlay to provide a translation of the added functionality, and adding an extension that locates a particular service endpoint of the API.
 

From 4c5cb9a941b01c1753c10888da063e4dfeaee9c3 Mon Sep 17 00:00:00 2001
From: Christian Vogel 
Date: Wed, 4 May 2016 18:05:06 +0100
Subject: [PATCH 225/241] wordsmithing default media types

---
 versions/raml-10/raml-10.md | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/versions/raml-10/raml-10.md b/versions/raml-10/raml-10.md
index 295e647f..3b284725 100644
--- a/versions/raml-10/raml-10.md
+++ b/versions/raml-10/raml-10.md
@@ -253,7 +253,7 @@ baseUri: https://na1.salesforce.com/services/data/{version}/chatter
 
 ### Default Media Types
 
-Specifying the OPTIONAL **mediaType** node sets the default for return by API requests having a body and for the expected responses. You do not need to specify the media type within every body definition.
+Specifying the OPTIONAL **mediaType** node sets the default media type for responses and requests that have a body. You do not need to specify the media type within every body definition.
 
 The value of the mediaType node MUST be a sequence of media type strings or a single media type string. The media type applies to requests having a body, the expected responses, and examples using the same sequence of media type strings. Each value needs to conform to the media type specification in [RFC6838](https://tools.ietf.org/html/rfc6838).
 

From 1c4d4b61244186ed947edf04c43cfeaebf93aa90 Mon Sep 17 00:00:00 2001
From: Christian Vogel 
Date: Thu, 5 May 2016 05:47:59 +0100
Subject: [PATCH 226/241] changed README file for release

---
 README.md | 10 +---------
 1 file changed, 1 insertion(+), 9 deletions(-)

diff --git a/README.md b/README.md
index 5b4c584b..5e5526cc 100644
--- a/README.md
+++ b/README.md
@@ -2,15 +2,13 @@
 
 RAML is a language for the definition of HTTP-based APIs that embody most or all of the principles of Representational State Transfer (REST). The RAML specification (this document) defines an application of the [YAML 1.2 specification](http://yaml.org/spec/1.2/spec.html) that provides mechanisms for the definition of practically-RESTful APIs, while providing provisions with which source code generators for client and server source code and comprehensive user documentation can be created.
 
-The current version of the RAML specification is **1.0** and can be found [here](versions/raml-10/raml-10.md).
-
 ## IMPORTANT NOTE
 
 RAML 1.0 is currently in a Release Candidate stage to gather feedback from the community around the features introduced in this version such as annotations or types. We will release the final version for 1.0 soon by announcing it on our [blog](http://blog.raml.org/).
 
 In the meanwhile, if you have any feedback, please report them [here](https://github.com/raml-org/raml-spec/issues).
 
-Current released version: 1.0 RC1
+Current released version: RAML 1.0 RC1
 
 ## Contributing
 
@@ -23,12 +21,6 @@ We welcome any contributions from the community! You can contribute or provide f
 
 You can also directly get in touch with us. Simply send us an email to: info@raml.org
 
-**Note**
-
-Currently we are working on RC2 inside another branch called `raml-10-rc2`. If you want to fix any spelling or grammar mistake, or an error in our examples, please fork that branch, make your edits, and then submit a pull request.
-
-More information around the current branch structure can be viewed [here](https://github.com/raml-org/raml-spec/wiki/RAML-1.0-RC2---Plan#branch-structure)
-
 ## Licensing
 
 [Branding Guidelines](http://raml.org/licensing.html)

From addc02dc43f19cb5ff60085119095d45a610f437 Mon Sep 17 00:00:00 2001
From: Christian Vogel 
Date: Thu, 5 May 2016 05:59:26 +0100
Subject: [PATCH 227/241] adjusted README for release

---
 README.md | 8 +-------
 1 file changed, 1 insertion(+), 7 deletions(-)

diff --git a/README.md b/README.md
index 5b4c584b..47c33042 100644
--- a/README.md
+++ b/README.md
@@ -10,7 +10,7 @@ RAML 1.0 is currently in a Release Candidate stage to gather feedback from the c
 
 In the meanwhile, if you have any feedback, please report them [here](https://github.com/raml-org/raml-spec/issues).
 
-Current released version: 1.0 RC1
+Current released version: 1.0 RC2
 
 ## Contributing
 
@@ -23,12 +23,6 @@ We welcome any contributions from the community! You can contribute or provide f
 
 You can also directly get in touch with us. Simply send us an email to: info@raml.org
 
-**Note**
-
-Currently we are working on RC2 inside another branch called `raml-10-rc2`. If you want to fix any spelling or grammar mistake, or an error in our examples, please fork that branch, make your edits, and then submit a pull request.
-
-More information around the current branch structure can be viewed [here](https://github.com/raml-org/raml-spec/wiki/RAML-1.0-RC2---Plan#branch-structure)
-
 ## Licensing
 
 [Branding Guidelines](http://raml.org/licensing.html)

From 6df09e5779688f0a8ca8f9e5b6893c0bf4194fa0 Mon Sep 17 00:00:00 2001
From: Christian Vogel 
Date: Thu, 5 May 2016 06:18:43 +0100
Subject: [PATCH 228/241] changed rc version inside README

---
 README.md | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/README.md b/README.md
index 5e5526cc..5ba3d8b3 100644
--- a/README.md
+++ b/README.md
@@ -8,7 +8,7 @@ RAML 1.0 is currently in a Release Candidate stage to gather feedback from the c
 
 In the meanwhile, if you have any feedback, please report them [here](https://github.com/raml-org/raml-spec/issues).
 
-Current released version: RAML 1.0 RC1
+Current released version: RAML 1.0 RC2
 
 ## Contributing
 

From 9766063b445231c10d6949a10a0ed8b537256ec2 Mon Sep 17 00:00:00 2001
From: Christian Vogel 
Date: Tue, 10 May 2016 10:17:13 +0100
Subject: [PATCH 229/241] added displayName to the possible facets inside an
 xml/json schema type

---
 versions/raml-10/raml-10.md | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/versions/raml-10/raml-10.md b/versions/raml-10/raml-10.md
index 3b284725..36596cdb 100644
--- a/versions/raml-10/raml-10.md
+++ b/versions/raml-10/raml-10.md
@@ -1239,7 +1239,7 @@ types:
             type: !include person.json
 ```
 
-A RAML processor MUST not allow types that define an XML or JSON schema to participate in type inheritance or specialization, or effectively in any [type expression](#type-expressions). Therefore, you cannot define sub-types of these types to declare new properties, add restrictions, set facets, or declare facets. You can, however, create simple type wrappers that add annotations, examples, or a description.
+A RAML processor MUST not allow types that define an XML or JSON schema to participate in type inheritance or specialization, or effectively in any [type expression](#type-expressions). Therefore, you cannot define sub-types of these types to declare new properties, add restrictions, set facets, or declare facets. You can, however, create simple type wrappers that add annotations, examples, displayName, or a description.
 
 The following example shows a valid declaration.
 

From 9a08faebdbe21f6fc76a15f5f87e9c6a62e6ccda Mon Sep 17 00:00:00 2001
From: Christian Vogel 
Date: Tue, 10 May 2016 10:44:44 +0100
Subject: [PATCH 230/241] removed redundant line about duplicated keys

---
 versions/raml-10/raml-10.md | 1 -
 1 file changed, 1 deletion(-)

diff --git a/versions/raml-10/raml-10.md b/versions/raml-10/raml-10.md
index 36596cdb..d7c163c6 100644
--- a/versions/raml-10/raml-10.md
+++ b/versions/raml-10/raml-10.md
@@ -101,7 +101,6 @@ To facilitate the automated processing of RAML documents, RAML imposes the follo
 
 * The first line of a RAML file consists of a YAML comment that specifies the RAML version. Therefore, RAML processors cannot completely ignore all YAML comments.
 * The order of some properties at certain levels within a RAML document is significant. Therefore, processors are expected to preserve this ordering.
-* Property names, also known as Keys, at certain levels are not repeatable. Although YAML allows such repetition, the value of a duplicate key, key 2 for example, overwrites the value of the duplicated key 1.
 
 ## The Root of the Document
 

From e1ed901bd2dda7efd03cecb042b9aa535697afe6 Mon Sep 17 00:00:00 2001
From: Christian Vogel 
Date: Fri, 13 May 2016 17:46:13 +0100
Subject: [PATCH 231/241] clarification on type expression for type declaration

---
 versions/raml-10/raml-10.md | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/versions/raml-10/raml-10.md b/versions/raml-10/raml-10.md
index d7c163c6..7a1ed137 100644
--- a/versions/raml-10/raml-10.md
+++ b/versions/raml-10/raml-10.md
@@ -417,7 +417,7 @@ types:
 
 ### Type Declarations
 
-A type declaration can extend a built-in type or other custom type, or add more information to types, such as specific examples or annotations. Here are the facets that all type declarations can have; certain type declarations might have other facets:
+A type declaration can extend a built-in type or other custom type using the type expression syntax, or add additional facets to types. Here are the facets that all type declarations can have; certain type declarations might have other facets:
 
 | Facet  | Description |
 |:----------|:----------|

From b162267f80142c06b43939789745423a347b79c3 Mon Sep 17 00:00:00 2001
From: Christian Vogel 
Date: Fri, 13 May 2016 18:13:12 +0100
Subject: [PATCH 232/241] wordsmithing previous change only

---
 versions/raml-10/raml-10.md | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/versions/raml-10/raml-10.md b/versions/raml-10/raml-10.md
index 7a1ed137..7b6aacaa 100644
--- a/versions/raml-10/raml-10.md
+++ b/versions/raml-10/raml-10.md
@@ -417,7 +417,7 @@ types:
 
 ### Type Declarations
 
-A type declaration can extend a built-in type or other custom type using the type expression syntax, or add additional facets to types. Here are the facets that all type declarations can have; certain type declarations might have other facets:
+A type declaration references another type, or wraps or extends another type by adding functional facets (e.g. properties) or non-functional facets (e.g. a description), or is a type expression that uses other types. Here are the facets that all type declarations can have; certain type declarations might have other facets:
 
 | Facet  | Description |
 |:----------|:----------|

From 0d83a603dff0ed25b9c02e8072b718b47c8da36f Mon Sep 17 00:00:00 2001
From: Christian Vogel 
Date: Mon, 16 May 2016 13:28:42 +0100
Subject: [PATCH 233/241] clarified what the value of resourcePathName should
 be

---
 versions/raml-10/raml-10.md | 10 +++++-----
 1 file changed, 5 insertions(+), 5 deletions(-)

diff --git a/versions/raml-10/raml-10.md b/versions/raml-10/raml-10.md
index 7b6aacaa..e707ef56 100644
--- a/versions/raml-10/raml-10.md
+++ b/versions/raml-10/raml-10.md
@@ -2143,16 +2143,16 @@ In resource type and trait declarations, **resourcePath** and **resourcePathName
 
 | Parameter | Value |
 |:---------|:-----------|
-| resourcePath | The full resource URI relative to the baseUri if there is one
-| resourcePathName | The rightmost path fragment of the relative resource URI, omitting any parametrizing brackets ("{" and "}")
+| resourcePath | The full resource URI relative to the baseUri if there is one.
+| resourcePathName | The rightmost of the non-URI-parameter-containing path fragments.
 
 Double angle brackets (double chevrons) enclose a parameter name in resource type and trait definitions; for example, `<>`.
 
-A processing application MUST set the value of `<>` to the concatenation of the relative (to the baseUri if there is one) resource URI of the inheriting resource and all its parent relative resource URIs. A processing application MUST set the value of `<>` at the position in the URI following the rightmost slash ("/"), omitting any parametrizing brackets ("{" and "}").
+A processing application MUST set the value of `<>` to the concatenation of the relative (to the baseUri if there is one) resource URI of the inheriting resource and all its parent relative resource URIs. A processing application MUST set the value of `<>` at the position in the URI following the rightmost slash ("/"), omitting any of the URI-parameter-containing path fragments.
 
-For example, applying a resource type or trait to a resource /users nested in a resource /{groupId} nested in a root-level resource /groups sets the value of the resourcePath parameter to /groups/{groupId}/users. Applying a resource type or trait to a resource /jobs/{jobId} sets the value of the resourcePathName parameter to jobId.
+For example, applying a resource type or trait to a resource /users nested in a resource /{groupId} nested in a root-level resource /groups sets the value of the resourcePath parameter to ""/groups/{groupId}/users". Applying a resource type or trait to a resource /jobs/{jobId} sets the value of the resourcePathName parameter to "jobs".
 
-When setting resourcePath and resourcePathName, processing applications MUST also omit any ext parameter and its parametrizing brackets ("{" and "}") found in the resource URI. For example, applying a resource type or trait to a root-level resource /bom/{itemId}{ext} sets the value of resourcePathName and resourcePath parameters to /bom/{itemId} and itemId, respectively.
+When setting resourcePath and resourcePathName, processing applications MUST also omit any ext parameter and its parametrizing brackets ("{" and "}") found in the resource URI. For example, applying a resource type or trait to a root-level resource /bom/{itemId}{ext} sets the value of resourcePathName and resourcePath parameters to "/bom/{itemId}" and "bom", respectively.
 
 In trait declarations, **methodName** is a reserved parameter.
 

From ee3141d280c8e3f11121a66d998be6e930c54836 Mon Sep 17 00:00:00 2001
From: petrochenko-pavel-a 
Date: Mon, 16 May 2016 20:29:14 +0700
Subject: [PATCH 234/241] Proposed changes based on investigation of
 https://github.com/raml-org/raml-js-parser-2/issues/177

Proposed changes based on investigation of https://github.com/raml-org/raml-js-parser-2/issues/177
---
 versions/raml-10/raml-10.md | 6 +++++-
 1 file changed, 5 insertions(+), 1 deletion(-)

diff --git a/versions/raml-10/raml-10.md b/versions/raml-10/raml-10.md
index e707ef56..4b859b8e 100644
--- a/versions/raml-10/raml-10.md
+++ b/versions/raml-10/raml-10.md
@@ -3218,7 +3218,7 @@ Overlays are particularly important for separating interface from implementation
 
 It is difficult to draw a definitive line between the behavioral and implementation-oriented aspects of the API because, for example, some semantics of the API are often captured only in human documentation. RAML does, however, define the specific behavior-invariance restrictions on overlay files that processors MUST follow. Processors can then choose to offer the master API definition as well as its modifications after applying one or more overlays, so the consumer can benefit from all the information available. For example, if overlay files are provided as a means of localizing textual descriptions of resources, methods, and data, the consumer of generated documentation can be offered a choice of which localized overlays to apply.
 
-The behavior-invariance restrictions of an overlay are defined as follows: after applying the [merging algorithm](#merging-rules) and before applying any inheritances of types, resource types, traits, and annotation types, the tree of nodes in the merged document is compared with the tree of nodes in the master RAML document after resolving all !include tags. Any differences in the documents MUST be only in the nodes listed in the following table.
+The behavior-invariance restrictions of an overlay are defined as follows: after applying the [merging algorithm](#merging-rules) as well as application of resource types and traits, the tree of nodes in the merged document is compared with the tree of nodes in the master RAML document after resolving all !include tags. Any differences in the documents MUST be only in the nodes listed in the following table.
 
 |Name | Allowed differences |
 |:--------|:------------|
@@ -3492,6 +3492,8 @@ All _includes_ are resolved and applied for both _Master Tree_ and _Extension Tr
 
 All _uses_ are resolved and applied for both _Master Tree_ and _Extension Tree_. The trees MUST NOT have _uses_ instructions with the same namespace referring to different files.
 
+All Trait and Resource Types applications are aplied in the _Master Tree_
+
 Initially, _Target Tree_ is made equal to the _Master Tree_.
 
 **Current Extension Tree Object** is set to the _Extension Tree_ root (API).
@@ -3516,6 +3518,8 @@ For each **Current Extension Tree Object property** the following is done:
   * All _Conflicting Properties_ are removed from the **Current Target Tree Object**
   * The **property** is added to the **Current Target Tree Object**.
 
+Traits and Resource Types applications are appled one more time to the _Target Tree_. 
+
 _Target Tree_ is validated.
 
 If the _Extension Tree_ is an Overlay, _Target Tree_ is compared to the _Master Tree_. There MUST NOT be any differences, other than those listed in the "Allowed differences" table in the [Overlays](#overlays) section. Otherwise the process is cancelled.

From 0f929b43000e49dcd2b07eb8c4136ff9848650ad Mon Sep 17 00:00:00 2001
From: petrochenko-pavel-a 
Date: Mon, 16 May 2016 20:49:00 +0700
Subject: [PATCH 235/241] Fixing couple of spelling errors

Fixing couple of spelling errors
---
 versions/raml-10/raml-10.md | 4 ++--
 1 file changed, 2 insertions(+), 2 deletions(-)

diff --git a/versions/raml-10/raml-10.md b/versions/raml-10/raml-10.md
index 4b859b8e..43f2e38e 100644
--- a/versions/raml-10/raml-10.md
+++ b/versions/raml-10/raml-10.md
@@ -3492,7 +3492,7 @@ All _includes_ are resolved and applied for both _Master Tree_ and _Extension Tr
 
 All _uses_ are resolved and applied for both _Master Tree_ and _Extension Tree_. The trees MUST NOT have _uses_ instructions with the same namespace referring to different files.
 
-All Trait and Resource Types applications are aplied in the _Master Tree_
+All Trait and Resource Types applications are applied in the _Master Tree_
 
 Initially, _Target Tree_ is made equal to the _Master Tree_.
 
@@ -3518,7 +3518,7 @@ For each **Current Extension Tree Object property** the following is done:
   * All _Conflicting Properties_ are removed from the **Current Target Tree Object**
   * The **property** is added to the **Current Target Tree Object**.
 
-Traits and Resource Types applications are appled one more time to the _Target Tree_. 
+Traits and Resource Types applications are applied one more time to the _Target Tree_. 
 
 _Target Tree_ is validated.
 

From b572da269aa8a0ea7b3aa1d5c9e5a4bf6791b74e Mon Sep 17 00:00:00 2001
From: Christian Vogel 
Date: Mon, 16 May 2016 19:28:50 +0100
Subject: [PATCH 236/241] fixed link issue to default media type section

---
 versions/raml-10/raml-10.md | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/versions/raml-10/raml-10.md b/versions/raml-10/raml-10.md
index e707ef56..7b0f4972 100644
--- a/versions/raml-10/raml-10.md
+++ b/versions/raml-10/raml-10.md
@@ -141,7 +141,7 @@ The following table enumerates the possible nodes at the root of a RAML document
 | baseUri? | A URI that serves as the [base for URIs](#base-uri-and-base-uri-parameters) of all resources. Often used as the base of the URL of each resource containing the location of the API. Can be a [template URI](#template-uri).
 | baseUriParameters? | Named parameters used in the [baseUri](#base-uri-and-base-uri-parameters) (template).
 | protocols? | The [protocols](#protocols) supported by the API.
-| mediaType? | The [default media types](#default-media-type) to use for request and response bodies (payloads), for example "application/json".
+| mediaType? | The [default media types](#default-media-types) to use for request and response bodies (payloads), for example "application/json".
 | documentation? | Additional overall [documentation](#user-documentation) for the API.
 | schemas? | An alias for the equivalent "types" node for compatibility with RAML 0.8. Deprecated - API definitions should use the "types" node because a future RAML version might remove the "schemas" alias with that node. The "types" node supports XML and JSON schemas.
 | types? | Declarations of [(data) types](#defining-types) for use within the API.

From 02818097023e7ac79b752adaa377a06173d12d3c Mon Sep 17 00:00:00 2001
From: Christian Vogel 
Date: Mon, 16 May 2016 19:32:50 +0100
Subject: [PATCH 237/241] fixed another link issue to default media types

---
 versions/raml-10/raml-10.md | 4 ++--
 1 file changed, 2 insertions(+), 2 deletions(-)

diff --git a/versions/raml-10/raml-10.md b/versions/raml-10/raml-10.md
index 4fefc419..4d1c9c85 100644
--- a/versions/raml-10/raml-10.md
+++ b/versions/raml-10/raml-10.md
@@ -1915,7 +1915,7 @@ baseUri: https://api.github.com/{version}
 
 The HTTP request **body** for a method is specified using the OPTIONAL body node. For example, to create a resource using a POST or PUT, the body of the request would usually include the details of the resource to be created.
 
-The value of the body node is a "body declaration". Generally, the body declaration is a map whose key names are the valid media types of the request body. Each key name MUST be a media type string conforming to the media type specification in [RFC6838](#https://tools.ietf.org/html/rfc6838). The values are the corresponding data type declaration or data type name describing the request body. Alternatively, if [default media types](#default-media-type) have been declared at the root of the API, then the body declaration can consist of just the data type declaration or data type name describing the request body for that media type.
+The value of the body node is a "body declaration". Generally, the body declaration is a map whose key names are the valid media types of the request body. Each key name MUST be a media type string conforming to the media type specification in [RFC6838](#https://tools.ietf.org/html/rfc6838). The values are the corresponding data type declaration or data type name describing the request body. Alternatively, if [default media types](#default-media-types) have been declared at the root of the API, then the body declaration can consist of just the data type declaration or data type name describing the request body for that media type.
 
 The following example illustrates various combinations of both default and non-default media types, and both data type declarations and references.
 
@@ -3518,7 +3518,7 @@ For each **Current Extension Tree Object property** the following is done:
   * All _Conflicting Properties_ are removed from the **Current Target Tree Object**
   * The **property** is added to the **Current Target Tree Object**.
 
-Traits and Resource Types applications are applied one more time to the _Target Tree_. 
+Traits and Resource Types applications are applied one more time to the _Target Tree_.
 
 _Target Tree_ is validated.
 

From ae12d2dd97e2d68067e39c780644f85504705ff1 Mon Sep 17 00:00:00 2001
From: Christian Vogel 
Date: Tue, 17 May 2016 07:01:48 +0100
Subject: [PATCH 238/241] removed BNF info from the introduction section

---
 versions/raml-10/raml-10.md | 6 +-----
 1 file changed, 1 insertion(+), 5 deletions(-)

diff --git a/versions/raml-10/raml-10.md b/versions/raml-10/raml-10.md
index e707ef56..4bcc89f3 100644
--- a/versions/raml-10/raml-10.md
+++ b/versions/raml-10/raml-10.md
@@ -89,11 +89,7 @@ RAML API definitions are YAML 1.2-compliant documents that begin with a REQUIRED
 title: My API
 ```
 
-The first line of a RAML specification-compliant document MUST match the [IETF RFC5234](https://tools.ietf.org/html/rfc5234) – Augmented BNF for Syntax Specifications:
-
-“#%RAML” SP “1.0” SP [FragmentType] CRLF
-
-The _FragmentType_ is NOT ALLOWED in API definitions and is OPTIONAL for the specification of [RAML fragment](#typed-fragments) documents. RAML fragment documents are reusable RAML modules that a larger API definition references or includes.
+The first line of a RAML API definition document MUST begin with the text _#%RAML_ followed by a single space followed by the text _1.0_ and nothing else before the end of the line. RAML fragment documents begin similarly with the RAML version comment and a [fragment identifier](#typed-fragments), but are not in themselves RAML API definition documents.
 
 The media type _application/raml+yaml_ and its associated file extension _.raml_ SHALL be used to designate files containing RAML API definitions, RAML fragments, and files that contain RAML markup. RAML is also capable of including documents of other media types, such as “application/schema+json” and “application/yaml”.
 

From b5c33ece68f945d07ac6937718a7e3de6d8e01c0 Mon Sep 17 00:00:00 2001
From: Christian Vogel 
Date: Tue, 17 May 2016 07:08:56 +0100
Subject: [PATCH 239/241] update README for GA

---
 README.md | 10 ++--------
 1 file changed, 2 insertions(+), 8 deletions(-)

diff --git a/README.md b/README.md
index 5ba3d8b3..712c6602 100644
--- a/README.md
+++ b/README.md
@@ -1,14 +1,8 @@
 # The RESTful API Modeling Language (RAML) Spec
 
-RAML is a language for the definition of HTTP-based APIs that embody most or all of the principles of Representational State Transfer (REST). The RAML specification (this document) defines an application of the [YAML 1.2 specification](http://yaml.org/spec/1.2/spec.html) that provides mechanisms for the definition of practically-RESTful APIs, while providing provisions with which source code generators for client and server source code and comprehensive user documentation can be created.
-
-## IMPORTANT NOTE
-
-RAML 1.0 is currently in a Release Candidate stage to gather feedback from the community around the features introduced in this version such as annotations or types. We will release the final version for 1.0 soon by announcing it on our [blog](http://blog.raml.org/).
+[![Gitter](https://img.shields.io/gitter/room/nwjs/nw.js.svg?maxAge=2592000)](https://gitter.im/raml-org/raml-spec)
 
-In the meanwhile, if you have any feedback, please report them [here](https://github.com/raml-org/raml-spec/issues).
-
-Current released version: RAML 1.0 RC2
+RAML is a language for the definition of HTTP-based APIs that embody most or all of the principles of Representational State Transfer (REST). The RAML specification (this document) defines an application of the [YAML 1.2 specification](http://yaml.org/spec/1.2/spec.html) that provides mechanisms for the definition of practically-RESTful APIs, while providing provisions with which source code generators for client and server source code and comprehensive user documentation can be created.
 
 ## Contributing
 

From d6ab7eb9c867c2ea166c66891f0c15e2f2a579c2 Mon Sep 17 00:00:00 2001
From: Christian Vogel 
Date: Tue, 17 May 2016 07:39:17 +0100
Subject: [PATCH 240/241] added table of content to 1.0

---
 versions/raml-10/raml-10.md | 92 +++++++++++++++++++++++++++++++++++++
 1 file changed, 92 insertions(+)

diff --git a/versions/raml-10/raml-10.md b/versions/raml-10/raml-10.md
index 2f83096b..adb6b0a1 100644
--- a/versions/raml-10/raml-10.md
+++ b/versions/raml-10/raml-10.md
@@ -45,6 +45,98 @@ RAML fully supports Level 2 as defined in [RFC6570](https://tools.ietf.org/html/
 
 Throughout this specification, **Markdown** means [GitHub-Flavored Markdown](https://help.github.com/articles/github-flavored-markdown/).
 
+## Table of Content
+
+
+
+- [Introduction](#introduction)
+- [What's New and Different in RAML 1.0](#whats-new-and-different-in-raml-10)
+- [Markup Language](#markup-language)
+- [The Root of the Document](#the-root-of-the-document)
+	- [User Documentation](#user-documentation)
+	- [Base URI and Base URI Parameters](#base-uri-and-base-uri-parameters)
+	- [Protocols](#protocols)
+	- [Default Media Types](#default-media-types)
+	- [Default Security](#default-security)
+- [RAML Data Types](#raml-data-types)
+	- [Introduction](#introduction)
+	- [Overview](#overview)
+	- [Defining Types](#defining-types)
+	- [Type Declarations](#type-declarations)
+	- [Object Types](#object-types)
+		- [Property Declarations](#property-declarations)
+		- [Additional Properties](#additional-properties)
+		- [Object Type Specialization](#object-type-specialization)
+		- [Using Discriminator](#using-discriminator)
+	- [Array Types](#array-types)
+	- [Scalar Types](#scalar-types)
+		- [String](#string)
+		- [Number](#number)
+		- [Integer](#integer)
+		- [Boolean](#boolean)
+		- [Date](#date)
+		- [File](#file)
+		- [Null Type](#null-type)
+	- [User-defined Facets](#user-defined-facets)
+	- [Determine Default Types](#determine-default-types)
+	- [Type Expressions](#type-expressions)
+	- [Union Types](#union-types)
+	- [Using XML and JSON Schema](#using-xml-and-json-schema)
+	- [Multiple Inheritance](#multiple-inheritance)
+	- [Inline Type Declarations](#inline-type-declarations)
+	- [Defining Examples in RAML](#defining-examples-in-raml)
+		- [Multiple Examples](#multiple-examples)
+		- [Single Example](#single-example)
+		- [Example of how to define example/examples in RAML](#example-of-how-to-define-exampleexamples-in-raml)
+	- [XML Serialization of Type Instances](#xml-serialization-of-type-instances)
+	- [Using Types in RAML](#using-types-in-raml)
+- [Resources and Nested Resources](#resources-and-nested-resources)
+	- [Resource Property](#resource-property)
+	- [Template URIs and URI Parameters](#template-uris-and-uri-parameters)
+- [Methods](#methods)
+	- [Headers](#headers)
+	- [Query Strings and Query Parameters](#query-strings-and-query-parameters)
+		- [The Query String as a Whole](#the-query-string-as-a-whole)
+		- [Query Parameters in a Query String](#query-parameters-in-a-query-string)
+	- [Bodies](#bodies)
+- [Responses](#responses)
+- [Resource Types and Traits](#resource-types-and-traits)
+	- [Declaration Resource Types and Traits](#declaration-resource-types-and-traits)
+	- [Applying Resource Types and Traits](#applying-resource-types-and-traits)
+	- [Resource Type and Trait Parameters](#resource-type-and-trait-parameters)
+	- [Declaring HTTP Methods as Optional](#declaring-http-methods-as-optional)
+	- [Algorithm of Merging Traits and Methods](#algorithm-of-merging-traits-and-methods)
+	- [Resource Types and Traits Effect on Collections](#resource-types-and-traits-effect-on-collections)
+- [Security Schemes](#security-schemes)
+	- [Security Scheme Types](#security-scheme-types)
+	- [Security Scheme Declaration](#security-scheme-declaration)
+		- [describedBy](#describedby)
+		- [Settings](#settings)
+			- [OAuth 1.0](#oauth-10)
+			- [OAuth 2.0](#oauth-20)
+			- [Basic Authentication](#basic-authentication)
+			- [Digest Authentication](#digest-authentication)
+			- [Pass Through](#pass-through)
+			- [x-<other>](#x-ltothergt)
+		- [Applying Security Schemes](#applying-security-schemes)
+- [Annotations](#annotations)
+	- [Declaring Annotation Types](#declaring-annotation-types)
+	- [Applying Annotations](#applying-annotations)
+		- [Annotating Scalar-valued Nodes](#annotating-scalar-valued-nodes)
+		- [Annotation Targets](#annotation-targets)
+- [Modularization](#modularization)
+	- [Includes](#includes)
+		- [Typed Fragments](#typed-fragments)
+		- [Resolving Includes](#resolving-includes)
+	- [Libraries](#libraries)
+	- [Overlays and Extensions](#overlays-and-extensions)
+		- [Overlays](#overlays)
+		- [Extensions](#extensions)
+		- [Merging Rules](#merging-rules)
+- [References](#references)
+
+
+
 ## Introduction
 
 This specification describes the RESTful API Modeling Language (RAML). RAML is a human- and machine-readable language for the definition of a RESTful application programming interface (API). RAML is designed to improve the specification of the API by providing a format that the API provider and API consumers can use as a mutual contract. RAML can, for example, facilitate providing user documentation and source code stubs for client and server implementations. Such provisions streamline and enhance the definition and development of interoperable applications that utilize RESTful APIs.

From 246e3d6f5705e3398faee461e0c8b7cc85a8216d Mon Sep 17 00:00:00 2001
From: Christian Vogel 
Date: Tue, 17 May 2016 07:51:33 +0100
Subject: [PATCH 241/241] removed 'removed' from the documentation node
 description of an overlay

---
 versions/raml-10/raml-10.md | 4 ++--
 1 file changed, 2 insertions(+), 2 deletions(-)

diff --git a/versions/raml-10/raml-10.md b/versions/raml-10/raml-10.md
index adb6b0a1..6ed5eebe 100644
--- a/versions/raml-10/raml-10.md
+++ b/versions/raml-10/raml-10.md
@@ -47,7 +47,7 @@ Throughout this specification, **Markdown** means [GitHub-Flavored Markdown](htt
 
 ## Table of Content
 
-
+
 
 - [Introduction](#introduction)
 - [What's New and Different in RAML 1.0](#whats-new-and-different-in-raml-10)
@@ -3315,7 +3315,7 @@ The behavior-invariance restrictions of an overlay are defined as follows: after
 | annotationTypes | The merged tree can include new annotation types or new values for existing annotation types, as long as all annotations in the merged API definition validate against the annotation types in the merged tree.
 | any annotation node | The merged tree can include new annotations of annotation types declared in the merged tree, or annotations with different values from those in the master tree.
 | examples | The merged tree can contain new named examples, or named examples with different values from those in the master tree.
-| documentation | The merged tree can contain new items in the array that is the value of the documentation root-level node. To change or remove existing items, the documentation node itself can be overridden in the overlay.
+| documentation | The merged tree can contain new items in the array that is the value of the documentation root-level node. To change existing items, the documentation node itself can be overridden in the overlay.
 
 The following example illustrates a very simple RAML definition of a library books API, along with overlay files that provide a Spanish translation and metadata for an API monitoring service.