From 27f530a7ff9a008e997965b6762a2ee16e383eda Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Sebasti=C3=A1n=20Ram=C3=ADrez?= <tiangolo@gmail.com>
Date: Fri, 28 Dec 2018 16:32:03 +0400
Subject: [PATCH] :memo: Update docs, clarify what's a schema

---
 README.md                    |  2 +-
 docs/index.md                |  2 +-
 docs/tutorial/first-steps.md | 34 ++++++++++++++++++++++++++++++++++
 3 files changed, 36 insertions(+), 2 deletions(-)

diff --git a/README.md b/README.md
index a783067fe..1c4b52341 100644
--- a/README.md
+++ b/README.md
@@ -291,7 +291,7 @@ Coming back to the previous code example, **FastAPI** will:
     * Check that it has an optional attribute `is_offer`, that should be a `bool`, if present.
     * All this would also work for deeply nested JSON objects.
 * Convert from and to JSON automatically.
-* Document everything as an OpenAPI schema, that can be used by:
+* Document everything with OpenAPI, that can be used by:
     * Interactive documentation sytems.
     * Automatic client code generation systems, for many languages.
 * Provide 2 interactive documentation web interfaces directly.
diff --git a/docs/index.md b/docs/index.md
index a783067fe..1c4b52341 100644
--- a/docs/index.md
+++ b/docs/index.md
@@ -291,7 +291,7 @@ Coming back to the previous code example, **FastAPI** will:
     * Check that it has an optional attribute `is_offer`, that should be a `bool`, if present.
     * All this would also work for deeply nested JSON objects.
 * Convert from and to JSON automatically.
-* Document everything as an OpenAPI schema, that can be used by:
+* Document everything with OpenAPI, that can be used by:
     * Interactive documentation sytems.
     * Automatic client code generation systems, for many languages.
 * Provide 2 interactive documentation web interfaces directly.
diff --git a/docs/tutorial/first-steps.md b/docs/tutorial/first-steps.md
index 5b41bfc4a..cf0809692 100644
--- a/docs/tutorial/first-steps.md
+++ b/docs/tutorial/first-steps.md
@@ -57,6 +57,32 @@ You will see the alternative automatic documentation (provided by <a href="https
 
 ![ReDoc](https://fastapi.tiangolo.com/img/index/index-02-redoc-simple.png)
 
+### OpenAPI
+
+**FastAPI** generates a "schema" with all your API using the **OpenAPI** standard for defining APIs.
+
+#### "Schema"
+
+A "schema" is a definition or description of something. Not the code that implements it, but just the abstract description.
+
+#### API "schema"
+
+In this case, OpenAPI is a specification that dictates how to define a schema of your API.
+
+This OpenAPI schema would include your API paths, the posible parameters they take, etc.
+
+#### Data "schema"
+
+The term "schema" might also refer to the shape of some data, like a JSON content.
+
+In that case, it would mean the JSON attributes, and data types they have, etc.
+
+#### OpenAPI and JSON Schema
+
+OpenAPI defines an API schema for your API. And that schema includes definitions (or "schemas") of the data sent and received by your API using **JSON Schema**, the standard for JSON data schemas.
+
+#### Check it
+
 If you are curious about how the raw OpenAPI schema looks like, it is just an automatically generated JSON with the descriptions of all your API.
 
 You can see it directly at: <a href="http://127.0.0.1:8000/openapi.json" target="_blank">http://127.0.0.1:8000/openapi.json</a>.
@@ -84,6 +110,14 @@ It will show a JSON starting with something like:
 ...
 ```
 
+#### What for?
+
+This OpenAPI schema is what powers the 2 interactive documentation systems included.
+
+And there are dozens of alternatives, all based on OpenAPI. You could easily add any of those alternatives to your application built with **FastAPI**.
+
+You could also use it to generate code automatically, for clients that communicate with your API. For example, frontend, mobile or IoT applications.
+
 ## Recap, step by step
 
 ### Step 1: import `FastAPI`