Skip to content

clarification about YAML #635

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 3 commits into from
Jun 6, 2016
Merged

clarification about YAML #635

Changes from all commits
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
bc59244
clarification about YAML
fehguy Apr 8, 2016
5e74e77
Updated YAML constraints
darrelmiller May 23, 2016
3720cb4
Limited YAML map keys to strings
darrelmiller May 23, 2016
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
7 changes: 6 additions & 1 deletion versions/3.0.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -51,7 +51,7 @@ The HTTP Status Codes are used to indicate the status of the executed operation.
### Format

The files describing the RESTful API in accordance with the OpenAPI Specification are represented as JSON objects and conform to the JSON standards. YAML, being a superset of JSON, can be used as well to
represent a OAS (OpenAPI Specification) file.
represent a OAS (OpenAPI Specification) file.

For example, if a field is said to have an array value, the JSON array representation will be used:

Expand All @@ -67,6 +67,11 @@ All field names in the specification are **case sensitive**.

The schema exposes two types of fields. Fixed fields, which have a declared name, and Patterned fields, which declare a regex pattern for the field name. Patterned fields can have multiple occurrences as long as each has a unique name.

In order to preserve the ability to round-trip between YAML and JSON formats, YAML version [1.2](http://www.yaml.org/spec/1.2/spec.html) is recommended along with some additional constraints:

- Tags MUST be limited to those allowed by the [JSON Schema ruleset](http://www.yaml.org/spec/1.2/spec.html#id2803231)
- Keys used in YAML maps MUST be limited to a scalar string, as defined by the YAML Failsafe schema ruleset

### File Structure

The OAS representation of the API is made of a single file. However, parts of the definitions can be split into separate files, at the discretion of the user. This is applicable for `$ref` fields in the specification as follows from the [JSON Schema](http://json-schema.org) definitions.
Expand Down