cdimascio
diff --git a/‎README.md
+1-5 b/‎README.md
+1-5
diff --git a/‎examples/1-standard-oas-3.1/README.md
+172 b/‎examples/1-standard-oas-3.1/README.md
+172
diff --git a/‎examples/1-standard-oas-3.1/api.yaml
+157 b/‎examples/1-standard-oas-3.1/api.yaml
+157
@@ -29,16 +29,12 @@
 [NestJS](https://github.com/cdimascio/express-openapi-validator/tree/master/examples/9-nestjs)
 [Koa](https://github.com/cdimascio/express-openapi-validator/tree/lerna-fastify/packages/koa-openapi-validator) and [Fastify](https://github.com/cdimascio/express-openapi-validator/tree/lerna-fastify/packages/fastify-openapi-validator) now available! 🚀
 
-[OAS 3.1 (experimental)](https://github.com/cdimascio/express-openapi-validator/pull/882)
+[OAS 3.1 (beta)](https://github.com/cdimascio/express-openapi-validator/pull/882) is available in v5.4.0!
 
 ## Install
 
 ```shell
 npm install express-openapi-validator
-
-# experimental OAS 3.1 in alpha (contributions welcome - see branch `oas-3.1` and pr-882 
-# please provide feedback on (issue-573)
-npm install [email protected]
 ```
 
 ## Usage
 
@@ -0,0 +1,172 @@
+# example
+
+simple example using express-openapi-validator
+
+## Install
+
+```shell
+npm run deps && npm i
+```
+
+## Run
+
+From this `1-standard` directory, run:
+
+```shell
+npm start
+```
+
+## Try
+
+```shell
+## call ping
+curl http://localhost:3000/v1/ping
+
+## call pets
+## the call below should return 400 since it requires additional parameters
+curl http://localhost:3000/v1/pets
+```
+
+## Text examples
+
+### GET /pets
+
+success
+```shell
+curl -s 'localhost:3000/v1/pets?limit=5' |jq
+[
+  {
+    "id": 1,
+    "name": "sparky",
+    "type": "dog",
+    "tags": [
+      "sweet"
+    ]
+  },
+  {
+    "id": 2,
+    "name": "buzz",
+    "type": "cat",
+    "tags": [
+      "purrfect"
+    ]
+  },
+  {
+    "id": 3,
+    "name": "max",
+    "type": "dog",
+    "tags": []
+  }
+]
+```
+
+error 
+```shell
+ curl -s 'localhost:3000/v1/pets' |jq
+{
+  "message": "request/query must have required property 'limit'",
+  "errors": [
+    {
+      "path": "/query/limit",
+      "message": "must have required property 'limit'",
+      "errorCode": "required.openapi.validation"
+    }
+  ],
+  "code": 400
+}
+```
+
+### POST /pets
+
+success
+```shell
+curl -s -XPOST 'localhost:3000/v1/pets' -d '{"id": 1, "name": "jobe"}' -H 'Content-type: application/json'|jq
+{
+  "id": 1,
+  "name": "jobe"
+}
+```
+
+error
+```shell
+curl -s -XPOST 'localhost:3000/v1/pets' -d '{"id": "sdfsf", "name": "jobe"}' -H 'Content-type: application/json'|jq
+{
+  "message": "request/body/id must be integer",
+  "errors": [
+    {
+      "path": "/body/id",
+      "message": "must be integer",
+      "errorCode": "type.openapi.validation"
+    }
+  ],
+  "code": 400
+}
+```
+
+### GET /pets/:id
+
+success
+```shell
+curl -s 'localhost:3000/v1/pets/1' |jq
+{
+  "id": 1,
+  "name": "sparky",
+  "type": "dog",
+  "tags": [
+    "sweet"
+  ]
+}
+```
+
+error: bad id type
+```shell
+curl -s 'localhost:3000/v1/pets/lkl' |jq
+{
+  "message": "request/params/petId must be number",
+  "errors": [
+    {
+      "path": "/params/petId",
+      "message": "must be number",
+      "errorCode": "type.openapi.validation"
+    }
+  ],
+  "code": 400
+}
+```
+
+
+### /v1/pets/1/photos
+
+success
+```shell
+curl  -XPOST 'localhost:3000/v1/pets/1/photos' -H 'Content-type: multipart/form-data' -F '[email protected]'|jq
+  % Total    % Received % Xferd  Average Speed   Time    Time     Time  Current
+                                 Dload  Upload   Total   Spent    Left  Speed
+100   304  100    90  100   214  25996  61813 --:--:-- --:--:-- --:--:--   98k
+{
+  "files_metadata": [
+    {
+      "originalname": "test.txt",
+      "encoding": "7bit",
+      "mimetype": "text/plain"
+    }
+  ]
+}
+```
+
+error: no file
+```shell
+ curl -s  -XPOST 'localhost:3000/v1/pets/1/photos' -H 'Content-type: multipart/form-data' |jq
+{
+  "message": "request/body must have required property 'file'",
+  "errors": [
+    {
+      "path": "/body/file",
+      "message": "must have required property 'file'",
+      "errorCode": "required.openapi.validation"
+    }
+  ],
+  "code": 400
+}
+```
+
@@ -0,0 +1,157 @@
+openapi: 3.1.0
+info:
+  version: 1.0.0
+  title: Swagger Petstore
+  license:
+    name: MIT
+    url: https://opensource.org/licenses/MIT
+servers:
+  - url: http://petstore.swagger.io/v1
+paths:
+  /pets:
+    get:
+      summary: List all pets
+      operationId: listPets
+      tags:
+        - pets
+      parameters:
+        - name: limit
+          in: query
+          description: How many items to return at one time (max 100)
+          required: true
+          schema:
+            type: integer
+            format: int32
+      responses:
+        '200':
+          description: A paged array of pets
+          headers:
+            x-next:
+              description: A link to the next page of responses
+              schema:
+                type: string
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/Pets'
+        default:
+          description: unexpected error
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/Error'
+    post:
+      summary: Create a pet
+      operationId: createPets
+      tags:
+        - pets
+      requestBody:
+        content:
+          application/json:
+            schema:
+              $ref: '#/components/schemas/Pet'
+      responses:
+        '201':
+          description: Null response
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/Pet'
+        default:
+          description: unexpected error
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/Error'
+  /pets/{id}:
+    get:
+      summary: Info for a specific pet
+      operationId: showPetById
+      tags:
+        - pets
+      parameters:
+        - name: id
+          in: path
+          required: true
+          description: The id of the pet to retrieve
+          schema:
+            type: number
+      responses:
+        '200':
+          description: Expected response to a valid request
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/Pet'
+        default:
+          description: unexpected error
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/Error'
+
+  /pets/{id}/photos:
+    post:
+      summary: upload a photo of the pet
+      operationId: uploadPetPhoto
+      parameters:
+        - name: id
+          in: path
+          description: ID of pet to fetch
+          required: true
+          schema:
+            type: integer
+            format: int64
+      requestBody:
+        content:
+          multipart/form-data:
+            schema:
+              type: object
+              required:
+                - file
+              properties:
+                file:
+                  description: The photo
+                  type: string
+                  format: binary
+        required: true
+      responses:
+        '200':
+          description: Null response
+          content:
+            application/json:
+              schema:
+                type: object
+                properties:
+                  success:
+                    type: boolean
+components:
+  schemas:
+    Pet:
+      type: object
+      required:
+        - id
+        - name
+      properties:
+        id:
+          type: integer
+          format: int64
+        name:
+          type: string
+        tag:
+          type: string
+    Pets:
+      type: array
+      items:
+        $ref: '#/components/schemas/Pet'
+    Error:
+      type: object
+      required:
+        - code
+        - message
+      properties:
+        code:
+          type: integer
+          format: int32
+        message:
+          type: string