Merge pull request OAI#1224 from MikeRalphson/introduction

Update intro wording, OAS definition [file] fixup

Author: RobDolinMS

versions/3.0.md

@@ -8,26 +8,22 @@ This document is licensed under [The Apache License, Version 2.0](http://www.apa
 
 ## Introduction
 
-The OpenAPI Specification (OAS) is a project that provides mechanisms to describe and document a RESTful API.
+The OpenAPI Specification (OAS) defines a standard, language-agnostic interface to RESTful APIs which allows both humans and computers to discover and understand the capabilities of the service without access to source code, documentation, or through network traffic inspection. When properly defined, a consumer can understand and interact with the remote service with a minimal amount of implementation logic.
 
-
-The OpenAPI Specification defines a set of files required to describe such APIs.
-These files can then be used by documentation generation tools to display the API and code generation tools to generate clients in various programming languages.
-
-Additional utilities, such as testing tools, can also use the files.
+An OpenAPI definition can then be used by documentation generation tools to display the API, code generation tools to generate servers and clients in various programming languages, testing tools and many other use cases.
 
 ## Table of Contents
 <!-- TOC depthFrom:1 depthTo:3 withLinks:1 updateOnSave:1 orderedList:0 -->
 
 - [Definitions](#definitions)
-	- [OpenAPI Definition File](#oasDefinitionFile)
+	- [OpenAPI Definition](#oasDefinition)
 	- [Path Templating](#pathTemplating)
 	- [Media Types](#mediaTypes)
 	- [HTTP Status Codes](#httpCodes)
 - [Specification](#specification)
 	- [Versions](#versions)
 	- [Format](#format)
-	- [File Structure](#fileStructure)
+	- [Document Structure](#documentStructure)
 	- [Data Types](#dataTypes)
 	- [Rich Text Formatting](#richText)
 	- [Relative References In URLs](#relativeReferences)
@@ -70,8 +66,8 @@ Additional utilities, such as testing tools, can also use the files.
 
 ## Definitions
 
-##### <a name="oasDefinitionFile"></a>OpenAPI Definition File
-A file or set of files which defines an API. The OpenAPI definition file uses and conforms to the OpenAPI Specification.
+##### <a name="oasDefinition"></a>OpenAPI Definition
+A document or set of documents which defines an API. An OpenAPI definition uses and conforms to the OpenAPI Specification.
 
 ##### <a name="pathTemplating"></a>Path Templating
 Path templating refers to the usage of curly braces ({}) to mark a section of a URL path as replaceable using path parameters.
@@ -107,7 +103,7 @@ The `major`.`minor` portion of the semver (for example `3.0`) SHALL designate th
 
 Subsequent minor version releases of the OpenAPI Specification (incrementing the `minor` version number) SHOULD NOT interfere with tooling developed to a lower minor version and same major version.  Thus a hypothetical `3.1.0` specification SHOULD be usable with tooling designed for `3.0.0`.
 
-An OpenAPI definition file compatible with OAS 3.\*.\* contains a required [`openapi`](#oasVersion) field which designates the semantic version of the OAS that it uses. (OAS 2.0 definition document contain a top-level version field named [`swagger`](http://swagger.io/specification/#swaggerObject) and value `"2.0"`.)
+An OpenAPI definition compatible with OAS 3.\*.\* contains a required [`openapi`](#oasVersion) field which designates the semantic version of the OAS that it uses. (OAS 2.0 definition documents contain a top-level version field named [`swagger`](http://swagger.io/specification/#swaggerObject) and value `"2.0"`.)
 
 ### Format
 
@@ -133,13 +129,13 @@ In order to preserve the ability to round-trip between YAML and JSON formats, YA
 
 **Note:** While APIs are described by OpenAPI documents in YAML or JSON format, the API request and response bodies and other content are not required to be JSON or YAML.
 
-### <a name="fileStructure"></a>File Structure
+### <a name="documentStructure"></a>Document Structure
 
-An OpenAPI definition file is made of a single file.
-However, parts of the definitions can be split into separate files, at the discretion of the user.
+An OpenAPI definition MAY be made up of a single document.
+However, parts of the definitions MAY be split into separate documents, 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.
 
-It is RECOMMENDED that the OpenAPI definition file be named following convention: `openapi.json` or `openapi.yaml`.
+It is RECOMMENDED that the root OpenAPI definition document be named: `openapi.json` or `openapi.yaml`.
 
 ### <a name="dataTypes"></a>Data Types
 
@@ -187,13 +183,13 @@ In the following description, if a field is not explicitly **REQUIRED** or descr
 
 #### <a name="oasObject"></a>OpenAPI Object
 
-This is the root document object of the [OpenAPI definition file](#oasDefinitionFile).
+This is the root document object of the [OpenAPI definition](#oasDefinition).
 
 ##### Fixed Fields
 
 Field Name | Type | Description
 ---|:---:|---
-<a name="oasVersion"></a>openapi | `string` | **REQUIRED**. This string MUST be the [semantic version number](http://semver.org/spec/v2.0.0.html) of the [OpenAPI Specification version](#versions) that the OpenAPI definition file uses. The `openapi` field SHOULD be used by tooling specifications and clients to interpret the OpenAPI definition file. This is *not* related to the API [`info.version`](#infoVersion) string.
+<a name="oasVersion"></a>openapi | `string` | **REQUIRED**. This string MUST be the [semantic version number](http://semver.org/spec/v2.0.0.html) of the [OpenAPI Specification version](#versions) that the OpenAPI definition uses. The `openapi` field SHOULD be used by tooling specifications and clients to interpret the OpenAPI definition. This is *not* related to the API [`info.version`](#infoVersion) string.
 <a name="oasInfo"></a>info | [Info Object](#infoObject) | **REQUIRED**. Provides metadata about the API. The metadata can be used by the clients if needed.
 <a name="oasServers"></a>servers | [[Server Object](#serverObject)] | An array of Server Objects, which provide connectivity information to a target server. If the `servers` property is not provided, or is an empty array, the default value would be a [Server Object](#serverObject) with a [url](#serverUrl) value of `/`.
 <a name="oasPaths"></a>paths | [Paths Object](#pathsObject) | **REQUIRED**. The available paths and operations for the API.
@@ -2268,7 +2264,7 @@ This object cannot be extended with additional properties and any properties add
 $ref: '#/components/schemas/Pet'
 ```
 
-##### Relative Schema File Example
+##### Relative Schema Document Example
 ```json
 {
   "$ref": "Pet.json"
@@ -2279,7 +2275,7 @@ $ref: '#/components/schemas/Pet'
 $ref: Pet.yaml
 ```
 
-##### Relative Files With Embedded Schema Example
+##### Relative Documents With Embedded Schema Example
 ```json
 {
   "$ref": "definitions.json#/Pet"