raml

type APIDefinition struct {
	RAMLVersion string `yaml:"-"`

	// A short, plain-text label for the API.
	Title string `yaml:"title" validate:"nonzero"`

	// The version of the API, for example "v1"
	Version string `yaml:"version"`

	// A URI that serves as the base for URIs 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.
	// 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 or a Template URI.
	BaseURI string `yaml:"baseUri"`

	// Named parameters used in the baseUri (template).
	BaseURIParameters map[string]NamedParameter `yaml:"baseUriParameters"`

	// The protocols supported by the API.
	// 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.
	Protocols []string `yaml:"protocols"`

	// The default media types to use for request and response bodies (payloads),
	// for example "application/json".
	// 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 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.
	MediaType string `yaml:"mediaType"`

	// Additional overall documentation for the API.
	// 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"`

	// 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.
	Schemas []map[string]string

	// Declarations of (data) types for use within the API.
	Types map[string]Type `yaml:"types"`

	// Declarations of traits for use within the API.
	Traits map[string]Trait `yaml:"traits"`

	// Declarations of resource types for use within the API.
	ResourceTypes map[string]ResourceType `yaml:"resourceTypes"`

	// Declarations of security schemes for use within the API.
	SecuritySchemes map[string]SecurityScheme `yaml:"securitySchemes"`

	// The security schemes that apply to every resource and method in the API.
	SecuredBy []DefinitionChoice `yaml:"securedBy"`

	// Imported external libraries for use within the API.
	Uses map[string]string `yaml:"uses"`

	// The resources of the API, identified as relative URIs that begin with a slash (/).
	// A resource property 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}.
	Resources map[string]Resource `yaml:",regexp:/.*"`

	Libraries map[string]*Library `yaml:"-"`

	Filename string
}

type Any interface{}

type Bodies struct {

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

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

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

	// 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:.*"`

	// TODO: For APIs without a priori knowledge of the response types for
	// their responses, "*/*" MAY be used to indicate that responses that do
	// not matching other defined data types MUST be accepted. Processing
	// applications MUST match the most descriptive media type first if
	// "*/*" is used.
	ApplicationJSON *BodiesProperty `yaml:"application/json"`

	// Request/response body type
	Type string `yaml:"type"`
}

type BodiesProperty struct {
	// we use `interface{}` as property type to support syntactic sugar & shortcut
	Properties map[string]interface{} `yaml:"properties"`

	Type interface{}

	Items interface{}
}

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"`

	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]interface{}

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

type Error struct {
	Errors []string
}

type HTTPCode string // e.g. 200

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

type HasProperties interface {
	GetProperty(string) Property
}

type Header NamedParameter

type Items struct {
	Type   string
	Format string
}

type JSONSchema struct {
	Schema      string              `json:"$schema"`
	Name        string              `json:"-"`
	Description string              `json:"description,omitempty"`
	Type        string              `json:"type"`
	T           *Type               `json:"-"` // underlying RAML type
	Items       *arrayItem          `json:"items,omitempty"`
	Properties  map[string]property `json:"properties,omitempty"`
	Required    []string            `json:"required,omitempty"`

	// Array properties
	MinItems    int  `json:"minItems,omitempty"`
	MaxItems    int  `json:"maxItems,omitempty"`
	UniqueItems bool `json:"uniqueItems,omitempty"`
}

type Library struct {
	Types           map[string]Type           `yaml:"types"`
	ResourceTypes   map[string]ResourceType   `yaml:"resourceTypes"`
	Traits          map[string]Trait          `yaml:"traits"`
	SecuritySchemes map[string]SecurityScheme `yaml:"securitySchemes"`
	Uses            map[string]string         `yaml:"uses"`

	// Describes the content or purpose of a specific library.
	// The value is a string and MAY be formatted using markdown.
	Usage string `yaml:"usage"`

	Libraries map[string]*Library `yaml:"-"`
	Filename  string              `yaml:"-"`
}

type Method struct {
	Name string

	// 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 string `yaml:"displayName"`

	// 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.
	Description string `yaml:"description"`

	// Detailed information about any query parameters needed by this method.
	// Mutually exclusive with queryString.
	// 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"`

	// Detailed information about any request headers needed by this method.
	Headers map[HTTPHeader]Header `yaml:"headers"`

	// The query string needed by this method.
	// Mutually exclusive with queryParameters.
	QueryString map[string]NamedParameter `yaml:"queryString"`

	// Information about the expected responses to a request.
	// 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"`

	// A request body that the method admits.
	Bodies Bodies `yaml:"body"`

	// 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 property.
	Protocols []string `yaml:"protocols"`

	// A list of the traits to apply to this method.
	Is []DefinitionChoice `yaml:"is"`

	// The security schemes that apply to this method.
	SecuredBy []DefinitionChoice `yaml:"securedBy"`
	// contains filtered or unexported fields
}

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 `yaml:"description"`

	// 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

	// 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 interface{}

	// 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 Processor interface {
	PostProcess(string, string) error
}

type Property struct {
	Name        string
	Type        interface{} `yaml:"type"`
	Required    bool        `yaml:"required"`
	Enum        interface{} `yaml:"enum"`
	Description string      `yaml:"description"`

	// string
	Pattern   *string
	MinLength *int
	MaxLength *int

	// number
	Minimum    *float64
	Maximum    *float64
	MultipleOf *float64
	Format     *string

	// array
	MinItems    *int
	MaxItems    *int
	UniqueItems bool
	Items       Items

	// Capnp extension
	CapnpType string
	// contains filtered or unexported fields
}

type Resource struct {

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

	// 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 string `yaml:"displayName"`

	// A substantial, human-friendly description of a resource.
	// Its value is a string and MAY be formatted using markdown.
	Description string `yaml:"description"`

	// 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"`
	Patch   *Method `yaml:"patch"`
	Put     *Method `yaml:"put"`
	Head    *Method `yaml:"head"`
	Post    *Method `yaml:"post"`
	Delete  *Method `yaml:"delete"`
	Options *Method `yaml:"options"`

	// A list of traits to apply to all methods declared (implicitly or explicitly) for this resource.
	// Individual methods can override this declaration.
	Is []DefinitionChoice `yaml:"is"`

	// The resource type that this resource inherits.
	Type *DefinitionChoice `yaml:"type"`

	// The security schemes that apply to all methods declared (implicitly or explicitly) for this resource.
	SecuredBy []DefinitionChoice `yaml:"securedBy"`

	// Detailed information about any URI parameters of this resource.
	URIParameters map[string]NamedParameter `yaml:"uriParameters"`

	// A nested resource, which is identified as any property
	// whose name begins with a slash ("/"), and is therefore treated as a relative URI.
	Nested map[string]*Resource `yaml:",regexp:/.*"`

	// 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

	// all methods of this resource
	Methods []*Method `yaml:"-"`
}

type ResourceType struct {

	// Name of the resource type
	Name string

	// The OPTIONAL usage property of a resource type 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 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"`

	// A list of traits to apply to all methods declared (implicitly or explicitly) for this resource type.
	// Individual methods can override this declaration.
	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"`
	Options *Method `yaml:"options"`

	// 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               *Method                   `yaml:"get?"`
	OptionalHead              *Method                   `yaml:"head?"`
	OptionalPost              *Method                   `yaml:"post?"`
	OptionalPut               *Method                   `yaml:"put?"`
	OptionalDelete            *Method                   `yaml:"delete?"`
	OptionalPatch             *Method                   `yaml:"patch?"`
	OptionalOptions           *Method                   `yaml:"options?"`
	// contains filtered or unexported fields
}

type Response struct {

	// HTTP status code of the response
	HTTPCode HTTPCode

	// A substantial, human-friendly description of a response.
	// Its value is a string and MAY be formatted using markdown.
	Description string

	// An API's methods may support custom header values in responses
	// Detailed information about any response headers returned by this method
	Headers map[HTTPHeader]Header `yaml:"headers"`

	// The body of the response
	Bodies Bodies `yaml:"body"`
}

type SecurityScheme struct {
	Name 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.
	// 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 string `yaml:"type"`

	// An alternate, human-friendly name for the security scheme.
	DisplayName string `yaml:"displayName"`

	// Information that MAY be used to describe a security scheme.
	// Its value is a string and MAY be formatted using markdown.
	Description string `yaml:"description"`

	// 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 SecuritySchemeMethod `yaml:"describedBy"`

	// The settings attribute MAY be used to provide security scheme-specific information.
	Settings map[string]Any `yaml:"settings"`
}

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

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?"`
}

type Type struct {
	Name string

	// A default value for a type
	Default interface{} `yaml:"default"`

	// 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.
	Schema interface{} `yaml:"schema"`

	// A base type which the current type extends,
	// or more generally a type expression.
	// 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.
	Type interface{} `yaml:"type" json:"type"`

	// 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.
	// 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.
	Example interface{} `yaml:"example" json:"example"`

	// 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.
	Examples map[string]interface{} `yaml:"examples" json:"examples"`

	// An alternate, human-friendly name for the type
	DisplayName string `yaml:"displayName" json:"displayName"`

	// A substantial, human-friendly description of the type.
	// Its value is a string and MAY be formatted using markdown.
	Description string `yaml:"description" json:"description"`

	// The properties that instances of this type may or must have.
	// we use `interface{}` as property type to support syntactic sugar & shortcut
	Properties map[string]interface{} `yaml:"properties" json:"properties"`

	// The minimum number of properties allowed for instances of this type.
	MinProperties int `yaml:"minProperties" json:"minProperties"`

	// The maximum number of properties allowed for instances of this type.
	MaxProperties int `yaml:"maxProperties" json:"maxProperties"`

	// A Boolean that indicates if an object instance has additional properties.
	// TODO: Default : true
	AdditionalProperties string `yaml:"additionalProperties" json:"additionalProperties"`

	// 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 with non-scalar properties.
	Discriminator string `yaml:"discriminator" json:"discriminator"`

	// 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.
	DiscriminatorValue string `yaml:"discriminatorValue" json:"discriminatorValue"`

	// Indicates the type all items in the array are inherited from.
	// Can be a reference to an existing type or an inline type declaration.
	Items interface{} `yaml:"items" json:"items"`

	// Minimum amount of items in array. Value MUST be equal to or greater than 0.
	MinItems int `yaml:"minItems" validate:"min=0" json:"minItems"`

	// Maximum amount of items in array. Value MUST be equal to or greater than 0.
	MaxItems int `yaml:"maxItems" validate:"min=0" json:"maxItems"`

	// Boolean value that indicates if items in the array MUST be unique.
	UniqueItems bool `yaml:"uniqueItems" json:"uniqueItems"`

	// ---------- facets for scalar type --------------------------//
	// 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.
	Enum interface{} `yaml:"enum" json:"enum"`

	// ---------- facets for string type ------------------------//
	// Regular expression that this string should match.
	Pattern string `yaml:"pattern" json:"pattern"`

	// Minimum length of the string. Value MUST be equal to or greater than 0.
	MinLength int `yaml:"minLength" validate:"min=0" json:"minLength"`

	// Maximum length of the string. Value MUST be equal to or greater than 0.
	MaxLength int `yaml:"maxLength" validate:"max=0" json:"maxLength"`

	// ----------- facets for Number -------------------------- //
	// The minimum value of the parameter. Applicable only to parameters of type number or integer.
	Minimum int `yaml:"minimum" json:"minimum"`

	// The maximum value of the parameter. Applicable only to parameters of type number or integer.
	Maximum int `yaml:"maximum" json:"maximum"`

	// The format of the value. The value MUST be one of the following:
	// int32, int64, int, long, float, double, int16, int8
	Format string `yaml:"format" json:"format"`

	// A numeric instance is valid against "multipleOf"
	// if the result of dividing the instance by this keyword's value is an integer.
	MultipleOf int `yaml:"multipleOf" json:"multipleOf"`

	// ---------- facets for file --------------------------------//
	// A list of valid content-type strings for the file. The file type */* MUST be a valid value.
	FileTypes string `yaml:"fileTypes" json:"fileTypes"`
	// contains filtered or unexported fields
}