raml

type APIDefinition struct {

	// RAML 0.8
	RAMLVersion string `yaml:"raml_version"`

	// The title property is a short plain text description of the RESTful API.
	// The title property's value SHOULD be suitable for use as a title for the
	// contained user documentation
	Title string `yaml:"title"`

	// If RAML API definition is targeted to a specific API version, it should
	// be noted here
	Version string `yaml:"version"`

	// A RESTful API's resources are defined relative to the API's base URI.
	// If the baseUri value is a Level 1 Template URI, the following reserved
	// base URI parameters are available for replacement:
	//
	// version - The content of the version field.
	BaseUri string

	// A resource or a method can override a base URI template's values.
	// This is useful to restrict or change the default or parameter selection
	// in the base URI. The baseUriParameters property MAY be used to override
	// any or all parameters defined at the root level baseUriParameters
	// property, as well as base URI parameters not specified at the root level.
	// In a resource structure of resources and nested resources with their
	// methods, the most specific baseUriParameter fully overrides any
	// baseUriParameter definition made before
	BaseUriParameters map[string]NamedParameter `yaml:"baseUriParameters"`

	// Level 1 URI custom parameters, which are useful in a variety of scenario.
	// URI parameters can be further defined by using the uriParameters
	// property. The use of uriParameters is OPTIONAL. The uriParameters
	// property MUST be a map in which each key MUST be the name of the URI
	// parameter as defined in the baseUri property. The uriParameters CANNOT
	// contain a key named version because it is a reserved URI parameter name.
	UriParameters map[string]NamedParameter `yaml:"uriParameters"`

	// A RESTful API can be reached HTTP, HTTPS, or both
	Protocols []string `yaml:"protocols"`

	// The media types returned by API responses, and expected from API
	// requests that accept a body, MAY be defaulted by specifying the
	// mediaType property.
	// The property's value MAY be a single string with a valid media type:
	//
	// One of the following YAML media types:
	// * text/yaml
	// * text/x-yaml
	// * application/yaml
	// * application/x-yaml*
	//
	// Any type from the list of IANA MIME Media Types,
	// http://www.iana.org/assignments/media-types
	// A custom type that conforms to the regular expression:
	// * "application\/[A-Za-z.-0-1]*+?(json|xml)"
	MediaType string `yaml:"mediaType"`

	// The schemas property specifies collections of schemas that could be
	// used anywhere in the API definition.
	// The value of the schemas property is an array of maps; in each map,
	// the keys are the schema name, and the values are schema definitions:
	// []map[SchemaName]SchemaString
	Schemas []map[string]string

	// The securitySchemes property MUST be used to specify an API's security
	// mechanisms, including the required settings and the authentication
	// methods that the API supports.
	// []map[SchemeName]SecurityScheme
	SecuritySchemes []map[string]SecurityScheme `yaml:"securitySchemes"`

	// To apply a securityScheme definition to every method in an API, the
	// API MAY be defined using the securedBy attribute. This specifies that
	// all methods in the API are protected using that security scheme.
	// Custom parameters can be provided to the security scheme.
	SecuredBy []DefinitionChoice `yaml:"securedBy"`

	// The API definition can include a variety of documents that serve as a
	// user guides and reference documentation for the API. Such documents can
	// clarify how the API works or provide business context.
	// All the sections are in the order in which the documentation is declared.
	Documentation []Documentation `yaml:"documentation"`

	// To apply a trait definition to a method, so that the method inherits the
	// trait's characteristics, the method MUST be defined by using the is
	// attribute. The value of the is attribute MUST be an array of any number
	// of elements, each of which MUST be a) one or more trait keys (names)
	// included in the traits declaration, or b) one or more trait definition
	// maps.
	// []map[TraitName]Trait
	Traits []map[string]Trait `yaml:"traits"`

	// The resourceTypes and traits properties are declared at the API
	// definition's root level with the resourceTypes and traits property keys,
	// respectively. The value of each of these properties is an array of maps;
	// in each map, the keys are resourceType or trait names, and the values
	// are resourceType or trait definitions, respectively.
	// []map[ResourceTypeName]ResourceType
	ResourceTypes []map[string]ResourceType `yaml:"resourceTypes"`

	// Resources are identified by their relative URI, which MUST begin with a
	// slash (/). 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. 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.
	Resources map[string]Resource `yaml:",regexp:/.*"`
}

type Any interface{}

type Bodies struct {

	// As in the Body type.
	DefaultSchema string `yaml:"schema"`

	// As in the Body type.
	DefaultDescription string `yaml:"description"`

	// As in the Body type.
	DefaultExample string `yaml:"example"`

	// As in the Body type.
	DefaultFormParameters map[string]NamedParameter `yaml:"formParameters"`

	// Resources CAN have alternate representations. For example, an API
	// might support both JSON and XML representations. This is the map
	// between MIME-type and the body definition related to it.
	ForMIMEType map[string]Body `yaml:",regexp:.*"`
}

type Body struct {

	// The structure of a request or response body MAY be further specified
	// by the schema property under the appropriate media type.
	// The schema key CANNOT be specified if a body's media type is
	// application/x-www-form-urlencoded or multipart/form-data.
	// All parsers of RAML MUST be able to interpret JSON Schema [JSON_SCHEMA]
	// and XML Schema [XML_SCHEMA].
	// Alternatively, the value of the schema field MAY be the name of a schema
	// specified in the root-level schemas property
	Schema string `yaml:"schema"`

	// Brief description
	Description string `yaml:"description"`

	// Example attribute to generate example invocations
	Example string `yaml:"example"`

	// Web forms REQUIRE special encoding and custom declaration.
	// If the API's media type is either application/x-www-form-urlencoded or
	// multipart/form-data, the formParameters property MUST specify the
	// name-value pairs that the API is expecting.
	// The formParameters property is a map in which the key is the name of
	// the web form parameter, and the value is itself a map the specifies
	// the web form parameter's attributes
	FormParameters map[string]NamedParameter `yaml:"formParameters"`

	Headers map[HTTPHeader]Header `yaml:"headers"`
	// contains filtered or unexported fields
}

type DefinitionChoice struct {
	Name string

	// The definitions 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 is provided by the processing application.
	// Same goes for security schemes.
	Parameters DefinitionParameters
}

type DefinitionParameters map[string]string

type Documentation struct {
	Title   string `yaml:"title"`
	Content string `yaml:"content"`
}

type HTTPCode int // e.g. 200

type HTTPHeader string // e.g. Content-Length

type Header NamedParameter

type Method struct {
	Name string

	// Briefly describes what the method does to the resource
	Description string

	// Applying a securityScheme definition to a method overrides whichever
	// securityScheme has been defined at the root level. To indicate that
	// the method is protected using a specific security scheme, the method
	// MUST be defined by using the securedBy attribute
	// Custom parameters can be provided to the security scheme.
	SecuredBy []DefinitionChoice `yaml:"securedBy"`

	// The method's non-standard HTTP headers. The headers property is a map
	// in which the key is the name of the header, and the value is itself a
	// map specifying the header attributes.
	Headers map[HTTPHeader]Header `yaml:"headers"`

	// A RESTful API method can be reached HTTP, HTTPS, or both.
	// A method can override an API's protocols value for that single method
	// by setting a different value for the fields.
	Protocols []string `yaml:"protocols"`

	// The queryParameters property is a map in which the key is the query
	// parameter's name, and the value is itself a map specifying the query
	//  parameter's attributes
	QueryParameters map[string]NamedParameter `yaml:"queryParameters"`

	// Some method verbs expect the resource to be sent as a request body.
	// A method's body is defined in the body property as a hashmap, in which
	// the key MUST be a valid media type.
	Bodies Bodies `yaml:"body"`

	// Resource methods MAY have one or more responses. Responses MAY be
	// described using the description property, and MAY include example
	// attributes or schema properties.
	// Responses MUST be a map of one or more HTTP status codes, where each
	// status code itself is a map that describes that status code.
	Responses map[HTTPCode]Response `yaml:"responses"`

	// Methods may specify one or more traits from which they inherit using the
	// is property
	Is []DefinitionChoice `yaml:"is"`
}

type NamedParameter struct {

	// The name of the Parameter, as defined by the type containing it.
	Name string

	// A friendly name used only for display or documentation purposes.
	// If displayName is not specified, it defaults to the property's key
	DisplayName string `yaml:"displayName"` // TODO: Auto-fill this

	// The intended use or meaning of the parameter
	Description string

	// The primitive type of the parameter's resolved value. Can be:
	//
	// Type	Description
	// string	- Value MUST be a string.
	// number	- Value MUST be a number. Indicate floating point numbers as defined by YAML.
	// integer	- Value MUST be an integer. Floating point numbers are not allowed. The integer type is a subset of the number type.
	// date		- Value MUST be a string representation of a date as defined in RFC2616 Section 3.3 [RFC2616]. See Date Representations.
	// boolean	- Value MUST be either the string "true" or "false" (without the quotes).
	// file		- (Applicable only to Form properties) Value is a file. Client generators SHOULD use this type to handle file uploads correctly.
	Type string

	// If the enum attribute is defined, API clients and servers MUST verify
	// that a parameter's value matches a value in the enum array
	Enum []Any `yaml:",flow"`

	// The pattern attribute is a regular expression that a parameter of type
	// string MUST match. Regular expressions MUST follow the regular
	// expression specification from ECMA 262/Perl 5. (string only)
	Pattern *string

	// The minLength attribute specifies the parameter value's minimum number
	// of characters (string only)
	MinLength *int `yaml:"minLength"`

	// The maxLength attribute specifies the parameter value's maximum number
	// of characters (string only)
	MaxLength *int `yaml:"maxLength"`

	// The minimum attribute specifies the parameter's minimum value. (numbers
	// only)
	Minimum *float64

	// The maximum attribute specifies the parameter's maximum value. (numbers
	// only)
	Maximum *float64

	// An example value for the property. This can be used, e.g., by
	// documentation generators to generate sample values for the property.
	Example string

	// The repeat attribute specifies that the parameter can be repeated,
	// i.e. the parameter can be used multiple times
	Repeat *bool // TODO: What does this mean?

	// Whether the parameter and its value MUST be present when a call is made.
	// In general, parameters are optional unless the required attribute is
	// included and its value set to 'true'.
	// For a URI parameter, its default value is 'true'.
	Required bool

	// The default value to use for the property if the property is omitted or
	// its value is not specified
	Default Any
	// contains filtered or unexported fields
}

type RamlError struct {
	Errors []string
}

type Resource struct {

	// Resources are identified by their relative URI, which MUST begin with
	// a slash (/).
	URI string

	// 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. If this is not nil, then this resource is a
	// child resource.
	Parent *Resource

	// A friendly name to the resource
	DisplayName string

	// Briefly describes the resource
	Description string

	// A securityScheme may also be applied to a resource by using the
	// securedBy key, which is equivalent to applying the securityScheme to
	// all methods of this Resource.
	// Custom parameters can be provided to the security scheme.
	SecuredBy []DefinitionChoice `yaml:"securedBy"`

	// A resource or a method can override a base URI template's values.
	// This is useful to restrict or change the default or parameter selection
	// in the base URI. The baseUriParameters property MAY be used to override
	// any or all parameters defined at the root level baseUriParameters
	// property, as well as base URI parameters not specified at the root level.
	// In a resource structure of resources and nested resources with their
	// methods, the most specific baseUriParameter fully overrides any
	// baseUriParameter definition made before
	BaseUriParameters map[string]NamedParameter `yaml:"baseUriParameters"`

	// Template URIs containing URI parameters can be used to define a
	// resource's relative URI when it contains variable elements.
	// The values matched by URI parameters cannot contain slash (/) characters
	UriParameters map[string]NamedParameter `yaml:"uriParameters"`

	// 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.
	// NOTE: inline not currently supported.
	Type *DefinitionChoice `yaml:"type"`

	// A resource may use the is property to apply the list of traits to all
	// its methods.
	Is []DefinitionChoice `yaml:"is"`

	// In a RESTful API, methods are operations that are performed on a
	// resource. A method MUST be one of the HTTP methods defined in the
	// HTTP version 1.1 specification [RFC2616] and its extension,
	// RFC5789 [RFC5789].
	Get    *Method `yaml:"get"`
	Head   *Method `yaml:"head"`
	Post   *Method `yaml:"post"`
	Put    *Method `yaml:"put"`
	Delete *Method `yaml:"delete"`
	Patch  *Method `yaml:"patch"`

	// 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.
	Nested map[string]*Resource `yaml:",regexp:/.*"`
}

type ResourceType struct {

	// Name of the resource type
	Name string

	// The usage property of a resource type or trait is used to describe how
	// the resource type or trait should be used
	Usage string

	// Briefly describes what the resource type
	Description string

	// As in Resource.
	UriParameters map[string]NamedParameter `yaml:"uriParameters"`

	// As in Resource.
	BaseUriParameters map[string]NamedParameter `yaml:"baseUriParameters"`

	// In a RESTful API, methods are operations that are performed on a
	// resource. A method MUST be one of the HTTP methods defined in the
	// HTTP version 1.1 specification [RFC2616] and its extension,
	// RFC5789 [RFC5789].
	Get    *ResourceTypeMethod `yaml:"get"`
	Head   *ResourceTypeMethod `yaml:"head"`
	Post   *ResourceTypeMethod `yaml:"post"`
	Put    *ResourceTypeMethod `yaml:"put"`
	Delete *ResourceTypeMethod `yaml:"delete"`
	Patch  *ResourceTypeMethod `yaml:"patch"`

	// When defining resource types and traits, it can be useful to capture
	// patterns that manifest several levels below the inheriting resource or
	// method, without requiring the creation of the intermediate levels.
	// For example, a resource type definition may describe a body parameter
	// that will be used if the API defines a post method for that resource,
	// but the processing application should not create the post method itself.
	//
	// This optional structure key indicates that the value of the property
	// 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.
	OptionalUriParameters     map[string]NamedParameter `yaml:"uriParameters?"`
	OptionalBaseUriParameters map[string]NamedParameter `yaml:"baseUriParameters?"`
	OptionalGet               *ResourceTypeMethod       `yaml:"get?"`
	OptionalHead              *ResourceTypeMethod       `yaml:"head?"`
	OptionalPost              *ResourceTypeMethod       `yaml:"post?"`
	OptionalPut               *ResourceTypeMethod       `yaml:"put?"`
	OptionalDelete            *ResourceTypeMethod       `yaml:"delete?"`
	OptionalPatch             *ResourceTypeMethod       `yaml:"patch?"`
}

type ResourceTypeMethod struct {
	Name string

	// Briefly describes what the method does to the resource
	Description string

	// As in Method.
	Bodies Bodies `yaml:"body"`

	// As in Method.
	Headers map[HTTPHeader]Header `yaml:"headers"`

	// As in Method.
	Responses map[HTTPCode]Response `yaml:"responses"`

	// As in Method.
	QueryParameters map[string]NamedParameter `yaml:"queryParameters"`

	// As in Method.
	Protocols []string `yaml:"protocols"`
}

type Response struct {

	// HTTP status code of the response
	HTTPCode HTTPCode

	// Clarifies why the response was emitted. Response descriptions are
	// particularly useful for describing error conditions.
	Description string

	// An API's methods may support custom header values in responses
	Headers map[HTTPHeader]Header `yaml:"headers"`

	// Each response MAY contain a body property. Responses that can return
	// more than one response code MAY therefore have multiple bodies defined.
	Bodies Bodies `yaml:"body"`
}

type SecurityScheme struct {
	Name string

	// Briefly describes the security scheme
	Description string

	// The type attribute MAY be used to convey information about
	// authentication flows and mechanisms to processing applications
	// such as Documentation Generators and Client generators.
	Type string

	// The describedBy attribute MAY be used to apply a trait-like structure
	// to a security scheme mechanism so as to extend the mechanism, such as
	// specifying response codes, HTTP headers or custom documentation.
	// This extension allows API designers to describe security schemes.
	// As a best practice, even for standard security schemes, API designers
	// SHOULD describe the security schemes' required artifacts, such as
	// headers, URI parameters, and so on.
	// Including the security schemes' description completes an API's documentation.
	DescribedBy SecuritySchemeMethod

	// The settings attribute MAY be used to provide security schema-specific
	// information. Depending on the value of the type parameter, its attributes
	// can vary.
	Settings map[string]Any

	// If the scheme's type is x-other, API designers can use the properties
	// in this mapping to provide extra information to clients that understand
	// the x-other type.
	Other map[string]string
}

type SecuritySchemeMethod struct {
	Bodies          Bodies                    `yaml:"body"`
	Headers         map[HTTPHeader]Header     `yaml:"headers"`
	Responses       map[HTTPCode]Response     `yaml:"responses"`
	QueryParameters map[string]NamedParameter `yaml:"queryParameters"`
}

type Trait struct {
	Name string

	// The usage property of a resource type or trait is used to describe how
	// the resource type or trait should be used
	Usage string

	// Briefly describes what the method does to the resource
	Description string

	// As in Method.
	Bodies Bodies `yaml:"body"`

	// As in Method.
	Headers map[HTTPHeader]Header `yaml:"headers"`

	// As in Method.
	Responses map[HTTPCode]Response `yaml:"responses"`

	// As in Method.
	QueryParameters map[string]NamedParameter `yaml:"queryParameters"`

	// As in Method.
	Protocols []string `yaml:"protocols"`

	// When defining resource types and traits, it can be useful to capture
	// patterns that manifest several levels below the inheriting resource or
	// method, without requiring the creation of the intermediate levels.
	// For example, a resource type definition may describe a body parameter
	// that will be used if the API defines a post method for that resource,
	// but the processing application should not create the post method itself.
	//
	// This optional structure key indicates that the value of the property
	// 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.
	OptionalBodies          Bodies                    `yaml:"body?"`
	OptionalHeaders         map[HTTPHeader]Header     `yaml:"headers?"`
	OptionalResponses       map[HTTPCode]Response     `yaml:"responses?"`
	OptionalQueryParameters map[string]NamedParameter `yaml:"queryParameters?"`
}